This is documentation for the next version of Grafana Alloy Documentation. For the latest stable release, go to the latest version.

Documentation Grafana Alloy Reference Components otelcol otelcol.connector.signaltometrics

otelcol.connector.signaltometrics

otelcol.connector.signaltometrics accepts spans, metric data points, and logs from other otelcol components and generates metrics from them using OpenTelemetry Transformation Language expressions. You can use it to produce sums, gauges, explicit bucket histograms, and exponential native histograms from any signal.

You can specify multiple otelcol.connector.signaltometrics components by giving them different labels.

Usage

Alloy Copy

otelcol.connector.signaltometrics "<LABEL>" {
  // One or more of spans, datapoints, or logs blocks.
  spans {
    name = "<METRIC_NAME>"
    // One of histogram, exponential_histogram, sum, or gauge.
    sum {
      value = "<OTTL_VALUE_EXPRESSION>"
    }
  }

  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.connector.signaltometrics:

The error_mode argument determines how the connector reacts to errors that occur while it evaluates an OTTL condition or expression during runtime data consumption. This setting doesn’t affect errors during OTTL parsing at configuration time, which always causes a startup failure. You can set error_mode to one of the following values:

• propagate: Return the error up the pipeline. Alloy drops the payload from the pipeline.
• ignore: Ignore the error and continue to process data. If an error occurs, Alloy skips the record and logs the error.
• silent: Ignore the error and continue to process data. If an error occurs, Alloy skips the record and doesn’t log the error.

Blocks

You can use the following blocks with otelcol.connector.signaltometrics:

spans

The spans block configures a metric generated from spans.

You can specify multiple spans blocks to define different metrics.

Each spans block must contain exactly one of the [histogram][histogram], [exponential_histogram][exponential_histogram], [sum][sum], or [gauge][gauge] blocks, which defines the type of metric to generate.

The conditions argument accepts a list of OTTL conditions that the connector combines with a logical OR. The connector processes data into the metric only when at least one condition evaluates to true. If you don’t specify conditions, the connector processes all data.

datapoints

The datapoints block configures a metric generated from metric data points.

You can specify multiple datapoints blocks to define different metrics.

This block shares the same configuration structure as [spans][spans]. Refer to the [spans][spans] block documentation for the complete list of supported arguments and blocks.

logs

The logs block configures a metric generated from log records.

You can specify multiple logs blocks to define different metrics.

This block shares the same configuration structure as [spans][spans]. Refer to the [spans][spans] block documentation for the complete list of supported arguments and blocks.

attributes

The attributes block specifies a data point attribute to group the generated metric by.

Each unique combination of attribute values generates a separate data point on the metric. You can specify multiple attributes blocks within a spans, datapoints, or logs block to group by multiple attributes.

You can use the following arguments:

You can set at most one of default_value or optional for a given attribute. If you don’t set either option, the connector drops data points that don’t have the attribute from the generated metric.

include_resource_attributes

The include_resource_attributes block specifies a resource attribute to include in the generated metric.

If you don’t specify any include_resource_attributes blocks, the connector includes all resource attributes. If you specify one or more blocks, the connector includes only the listed resource attributes.

This block supports the same arguments as the [attributes][attributes] block.

histogram

The histogram block generates an explicit bucket histogram metric.

If you don’t specify buckets, the connector uses the following default boundaries: [2, 4, 6, 8, 10, 50, 100, 200, 400, 800, 1000, 1400, 2000, 5000, 10000, 15000].

If you don’t specify count, each matching record increments the count by one.

exponential_histogram

The exponential_histogram block generates a base-2 exponential native histogram metric.

If you don’t specify count, each matching record increments the count by one.

sum

The sum block generates a sum metric.

gauge

The gauge block generates a gauge metric.

output

debug_metrics

Exported fields

The following fields are exported and can be referenced by other components:

input accepts otelcol.Consumer data for traces, metrics, and logs. The connector generates metrics from the received telemetry according to the configured blocks and emits them to the components specified in output.

Component health

otelcol.connector.signaltometrics is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.connector.signaltometrics doesn’t expose any component-specific debug information.

Examples

Generate a native histogram from log lines

The following example generates an exponential native histogram of log body lengths and exports it over OTLP. The connector emits an OTLP exponential histogram, which an OTLP-compatible backend stores as a Prometheus native histogram, so the telemetry stays OTLP-native end to end.

The connector emits delta metrics on each incoming batch, so this example routes them through otelcol.processor.deltatocumulative and otelcol.processor.interval to bound the number of data points produced per minute. Refer to Control the number of data points per minute for the rationale.

Alloy Copy

otelcol.connector.signaltometrics "default" {
  logs {
    name        = "log.body.length"
    description = "Distribution of log body lengths"
    exponential_histogram {
      value = "Len(body)"
    }
  }

  output {
    metrics = [otelcol.processor.deltatocumulative.default.input]
  }
}

otelcol.processor.deltatocumulative "default" {
  output {
    metrics = [otelcol.processor.interval.default.input]
  }
}

otelcol.processor.interval "default" {
  interval = "60s"

  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = "http://localhost:4318"
  }
}

Generate metrics from spans

The following example generates a span duration histogram and a request counter grouped by HTTP method. As with the previous example, the connector’s delta metrics are routed through otelcol.processor.deltatocumulative and otelcol.processor.interval to limit the number of data points produced per minute.

Alloy Copy

otelcol.connector.signaltometrics "default" {
  spans {
    name        = "span.duration"
    description = "Span duration in milliseconds"
    unit        = "ms"
    histogram {
      value = "Milliseconds(end_time - start_time)"
    }
  }

  spans {
    name        = "http.server.request.count"
    description = "Number of HTTP server requests"
    attributes {
      key = "http.request.method"
    }
    sum {
      value = "1"
    }
  }

  output {
    metrics = [otelcol.processor.deltatocumulative.default.input]
  }
}

otelcol.processor.deltatocumulative "default" {
  output {
    metrics = [otelcol.processor.interval.default.input]
  }
}

otelcol.processor.interval "default" {
  interval = "60s"

  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = "http://localhost:4318"
  }
}

Control the number of data points per minute

otelcol.connector.signaltometrics produces metrics whenever it receives a batch of telemetry, using delta temporality. It has no flush interval of its own, so the rate at which it produces data points is governed by how often upstream components send it data, not by any scrape interval. If you export these metrics directly, it can produce many data points per minute for each series, which increases cost on backends that price per data point, such as those contracted to one data point per minute, equivalent to a 60-second scrape interval.

To limit the rate, place an otelcol.processor.deltatocumulative and an otelcol.processor.interval processor between the connector and the exporter, as shown in the previous examples:

• deltatocumulative converts the connector’s delta metrics into cumulative temporality. This step is required because interval only aggregates cumulative metrics and passes delta metrics through unchanged.
• interval forwards the latest value of each series once per interval. Its default interval is 60s, which emits one data point per series each minute.

Cumulative temporality is also what Prometheus-compatible backends store natively, so this pipeline suits writing native histograms to Grafana Cloud.

Compatible components

otelcol.connector.signaltometrics can accept arguments from the following components:

• Components that export OpenTelemetry otelcol.Consumer

otelcol.connector.signaltometrics has exports that can be consumed by the following components:

• Components that consume OpenTelemetry otelcol.Consumer