Menu

Caution

Grafana Alloy is the new name for our distribution of the OTel collector. Grafana Agent has been deprecated and is in Long-Term Support (LTS) through October 31, 2025. Grafana Agent will reach an End-of-Life (EOL) on November 1, 2025. Read more about why we recommend migrating to Grafana Alloy.

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

DocumentationGrafana AgentFlow modeReferenceComponents referenceotelcol.connector.spanlogs
Open source

otelcol.connector.spanlogs

otelcol.connector.spanlogs accepts traces telemetry data from other otelcol components and outputs logs telemetry data for each span, root, or process. This allows you to automatically build a mechanism for trace discovery.

NOTE: otelcol.connector.spanlogs is a custom component unrelated to any components from the OpenTelemetry Collector. It is based on the automatic_logging component in the traces subsystem of the Agent static mode.

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

Usage

river 
otelcol.connector.spanlogs "LABEL" {
  output {
    logs    = [...]
  }
}

Arguments

otelcol.connector.spanlogs supports the following arguments:

NameTypeDescriptionDefaultRequired
spansboolLog one line per span.falseno
rootsboolLog one line for every root span of a trace.falseno
processesboolLog one line for every process.falseno
span_attributeslist(string)Additional span attributes to log.[]no
process_attributeslist(string)Additional process attributes to log.[]no
labelslist(string)A list of keys that will be logged as labels.[]no

The values listed in labels should be the values of either span or process attributes.

WARNING: Setting spans to true could lead to a high volume of logs.

Blocks

The following blocks are supported inside the definition of otelcol.connector.spanlogs:

HierarchyBlockDescriptionRequired
overridesoverridesOverrides for keys in the log body.no
outputoutputConfigures where to send received telemetry data.yes

overrides block

The overrides block configures overrides for keys that will be logged in the body of the log line.

The following attributes are supported:

NameTypeDescriptionDefaultRequired
logs_instance_tagstringIndicates if the log line is for a span, root, or process.tracesno
service_keystringLog key for the service name of the resource.svcno
span_name_keystringLog key for the name of the span.spanno
status_keystringLog key for the status of the span.statusno
duration_keystringLog key for the duration of the span.durno
trace_id_keystringLog key for the trace ID of the span.tidno

output block

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
logslist(otelcol.Consumer)List of consumers to send logs to.[]no

You must specify the output block, but all its arguments are optional. By default, telemetry data is dropped. Configure the logs argument accordingly to send telemetry data to other components, .

Exported fields

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

NameTypeDescription
inputotelcol.ConsumerA value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

otelcol.connector.spanlogs does not expose any component-specific debug information.

Example

The following configuration sends logs derived from spans to Loki.

Additionally, otelcol.processor.attributes is configured with a “hint” so that otelcol.exporter.loki promotes the span’s “attribute1” attribute to a Loki label.

river 
otelcol.receiver.otlp "default" {
  grpc {}

  output {
    traces = [otelcol.connector.spanlogs.default.input]
  }
}

otelcol.connector.spanlogs "default" {
  spans              = true
  roots              = true
  processes          = true
  labels             = ["attribute1", "res_attribute1"]
  span_attributes    = ["attribute1"]
  process_attributes = ["res_attribute1"]

  output {
    logs = [otelcol.processor.attributes.default.input]
  }
}

otelcol.processor.attributes "default" {
  action {
    key = "loki.attribute.labels"
    action = "insert"
    value = "attribute1"
  }

  output {
    logs = [otelcol.exporter.loki.default.input]
  }
}

otelcol.exporter.loki "default" {
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100"
  }
}

For an input trace like this…

json 
{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "res_attribute1",
            "value": { "intValue": "78" }
          },
          {
            "key": "unused_res_attribute1",
            "value": { "stringValue": "str" }
          },
          {
            "key": "res_account_id",
            "value": { "intValue": "2245" }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
              "span_id": "086e83747d0e381e",
              "name": "TestSpan",
              "attributes": [
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "unused_attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "account_id",
                  "value": { "intValue": "2245" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

… the output log coming out of otelcol.connector.spanlogs will look like this:

json 
{
  "resourceLogs": [
    {
      "scopeLogs": [
        {
          "log_records": [
            {
              "body": {
                "stringValue": "span=TestSpan dur=0ns attribute1=78 svc=TestSvcName res_attribute1=78 tid=7bba9f33312b3dbb8b2c2c62bb7abe2d"
              },
              "attributes": [
                {
                  "key": "traces",
                  "value": { "stringValue": "span" }
                },
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "res_attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            },
            {
              "body": {
                "stringValue": "span=TestSpan dur=0ns attribute1=78 svc=TestSvcName res_attribute1=78 tid=7bba9f33312b3dbb8b2c2c62bb7abe2d"
              },
              "attributes": [
                {
                  "key": "traces",
                  "value": { "stringValue": "root" }
                },
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "res_attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            },
            {
              "body": {
                "stringValue": "svc=TestSvcName res_attribute1=78 tid=7bba9f33312b3dbb8b2c2c62bb7abe2d"
              },
              "attributes": [
                {
                  "key": "traces",
                  "value": { "stringValue": "process" }
                },
                {
                  "key": "res_attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Compatible components

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

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

Note

Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.