README.md

Building and running a custom collector with sqlparamstyle

The sqlparamstyle processor is a custom component: it is not included in the standard OpenTelemetry Collector distribution. To use it you build your own collector binary that includes this processor, then run that binary with a config that enables the processor in a pipeline.

This guide walks you through that in order: configure the processor (runtime config), configure the custom collector (which components to bake into the binary), build the binary, and run it.

1. Configure the processor (runtime config)

You need a collector config file that defines pipelines and enables the sqlparamstyle processor. The processor normalizes parameterized SQL in span attributes (e.g. db.statement) so traces group by query shape instead of literal values.

File: examples/collector-config.yaml

Relevant parts:

• Processors: sqlparamstyle with:
  • attribute_keys: list of span attribute names to normalize (e.g. db.statement).
  • normalize_in_clause: if true, reduces IN (?, ?, ?) to a single placeholder for better grouping.
• Pipeline: a traces pipeline that uses sqlparamstyle (and e.g. batch) between receivers and exporters.

processors:
  sqlparamstyle:
    attribute_keys:
      - db.statement
    normalize_in_clause: true

  batch:
    timeout: 10s

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [sqlparamstyle, batch]
      exporters: [debug]

You will pass this file to the collector when you run it (step 4). No changes are required for the rest of this guide; you can edit it later to add receivers/exporters or tune the processor.

2. Configure the custom collector (builder manifest)

Because the processor is not in the default distribution, you define a custom distribution by listing the components to include. The OpenTelemetry Collector Builder reads a manifest and generates a Go project that compiles to a single binary containing only those components.

File: examples/builder-config.yaml

• dist: name of the binary (custom-otelcol), output directory (./dist), and optional module/version/otelcol version.
• receivers / processors / exporters: list of components. Core components are pulled by gomod (e.g. batchprocessor, otlpreceiver). This repo's processor is included as a processor component, either via a published module or a local checkout:

processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.147.0
  - gomod: go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.147.0
  # sqlparamstyle: PEP 249 paramstyle normalization for trace attribute_keys (e.g. db.statement)
  - gomod: github.com/nilox94/otel-sqlparamstyle-processor v0.1.0

Use the gomod: github.com/nilox94/otel-sqlparamstyle-processor v0.1.0 line to depend on a published version of this processor. To build against a local checkout instead, add a path field to the same processor entry:

  - gomod: github.com/nilox94/otel-sqlparamstyle-processor v0.1.0
    path: /path/to/otel-sqlparamstyle-processor

3. Build the custom collector binary

Install the Collector Builder (if you haven't already). It is published as the builder binary when installed via Go:

go install go.opentelemetry.io/collector/cmd/builder@v0.147.0

From the repository root, run the builder with the manifest from step 2:

builder --config=examples/builder-config.yaml

When it finishes, the custom collector binary is at:

./dist/custom-otelcol

4. Run the custom collector

Start the collector with the runtime config from step 1:

./dist/custom-otelcol --config=examples/collector-config.yaml

Send traces whose spans have parameterized SQL in the configured attributes (e.g. db.statement). The sqlparamstyle processor will normalize placeholder styles and, if normalize_in_clause is enabled, collapse IN lists so that traces group by query shape.