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.exceptions

otelcol.connector.exceptions

otelcol.connector.exceptions accepts traces and logs from other otelcol components and outputs logs and metrics that describe the exceptions recorded in them.

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

otelcol.connector.exceptions treats a span event named exception and a log record with the event name exception as exceptions. These follow the semantic conventions for exceptions in spans and logs.

Depending on the signals you set in the output block, otelcol.connector.exceptions does the following:

• Traces to logs: Converts each exception span event into a log record that follows the semantic conventions for exceptions in logs. The log record carries the span attributes, the trace and span IDs, and the exception.type, exception.message, and exception.stacktrace attributes of the event. Use this to move exception tracking from spans to logs while applications still report exceptions as span events.
• Logs to logs: Forwards log records with the event name exception and drops all other log records. Use this to route exception logs to a dedicated backend.
• Traces to metrics and logs to metrics: Increments an exceptions counter metric for every exception found in spans or log records.

Traces to logs, traces to metrics, and logs to metrics require the service.name resource attribute. otelcol.connector.exceptions skips any resource that doesn’t set it. Logs to logs forwards exception log records whether or not the resource sets service.name.

Usage

Alloy Copy

otelcol.connector.exceptions "<LABEL>" {
  output {
    logs    = [...]
    metrics = [...]
  }
}

Arguments

You can use the following argument with otelcol.connector.exceptions:

You can’t specify a dimension block when disable_default_dimensions is true. A dimension block already replaces the default dimensions.

Blocks

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

output

debug_metrics

dimension

The dimension block configures an attribute to add to the log records converted from span events and to the emitted metric data points.

Each converted log record and metric data point has the following attributes:

• service.name
• span.name
• span.kind
• status.code

The span.name, span.kind, and status.code attributes are only added when the exception comes from a span.

You can specify multiple dimension blocks. When you don’t specify any dimension block, Alloy adds the exception.type and exception.message dimensions. When you specify at least one dimension block, Alloy adds only the dimensions you list. To add no dimensions beyond the attributes listed previously, set disable_default_dimensions to true and specify no dimension block.

The following arguments are supported:

When the input signal is traces, otelcol.connector.exceptions looks for the name attribute in the span attributes, then in the span event attributes, and finally in the resource attributes. When the input signal is logs, it looks in the log record attributes and then in the resource attributes.

If the attribute is missing:

• If you don’t set default, otelcol.connector.exceptions omits the dimension.
• If you set default, otelcol.connector.exceptions adds the dimension with that value.

Each dimension block must have a unique name. You can’t use service.name, span.name, span.kind, or status.code as a dimension name because they’re already added by default.

Converted log records always carry the exception.type, exception.message, and exception.stacktrace attributes when they’re present on the span event, regardless of the configured dimensions.

exemplars

The exemplars block configures how to attach exemplars to the exceptions metric.

The following arguments are supported:

otelcol.connector.exceptions only records an exemplar when the span or log record carries a trace ID.

Exported fields

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

input accepts otelcol.Consumer traces and logs telemetry data. It doesn’t accept metrics.

Component health

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

Debug information

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

Debug metrics

otelcol.connector.exceptions doesn’t expose any component-specific debug metrics.

Examples

Convert span exceptions to logs

The following example accepts traces, converts the exceptions recorded on spans into log records, writes the log records to Loki, and writes the traces to Tempo.

Alloy Copy

otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "0.0.0.0:4317"
  }

  output {
    traces = [
      otelcol.connector.exceptions.default.input,
      otelcol.exporter.otlphttp.tempo.input,
    ]
  }
}

otelcol.connector.exceptions "default" {
  output {
    logs = [otelcol.exporter.otlphttp.loki.input]
  }
}

otelcol.exporter.otlphttp "loki" {
  client {
    endpoint = "http://loki:3100/otlp"
  }
}

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

Filter exception logs and count exceptions

The following example accepts logs, forwards only the log records that describe exceptions to a dedicated backend, and writes a metric counting exceptions to Mimir. The metric also has an http.method label taken from the log record or resource attributes.

Alloy Copy

otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "0.0.0.0:4317"
  }

  output {
    logs = [otelcol.connector.exceptions.default.input]
  }
}

otelcol.connector.exceptions "default" {
  dimension {
    name = "exception.type"
  }

  dimension {
    name    = "http.method"
    default = "unknown"
  }

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

otelcol.exporter.otlphttp "exceptions" {
  client {
    endpoint = "http://exceptions-backend:4318"
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

The metric in Mimir looks like this:

text Copy

exceptions_total{service_name="shop-backend",exception_type="NullPointerException",http_method="GET"}

Compatible components

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

• Components that export OpenTelemetry otelcol.Consumer

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

• Components that consume OpenTelemetry otelcol.Consumer