Skip to main content

Telemetry policy

Use the telemetry policy to configure an OpenTelemetry collector for Stacklok client traces and metrics. For a primer on ToolHive's OpenTelemetry support, see the OpenTelemetry integration guide.

You'll need the OTLP HTTP endpoint for your collector (for example, https://otel.example.com) and the Enterprise Manager already deployed and reachable by clients.

Configure the telemetry directive​

Add the telemetry directive to your enterprise configuration. Replace the example endpoint and headers with your collector's settings and pick an enforcement level.

values.yaml
enterpriseConfig:
  telemetry:
    value:
      # Required: OTLP HTTP endpoint for your OpenTelemetry collector
      otel_endpoint: 'https://otel.example.com'
      # Fraction of traces to sample: 0.0 = none, 1.0 = all
      sampling_rate: 0.1
      tracing_enabled: true
      metrics_enabled: true
      # Non-sensitive headers only; do not include API keys or credentials
      headers:
        x-tenant-id: 'acme-prod'
    # "enforced" blocks local overrides; "default" lets users override locally
    enforcement: 'enforced'

Use enforced to require the central collector. Use default to let client operators override the settings for local debugging or testing.

warning

The headers field is for non-sensitive metadata only (tenant ID, environment name, and so on). Do not include API keys, tokens, or other credentials here. Use your identity provider and OIDC token exchange for authenticated collector access.

After updating your configuration, apply the change.

Variations​

Advisory telemetry settings​

Push OpenTelemetry settings as org-wide defaults while allowing teams to override them:

values.yaml
enterpriseConfig:
  telemetry:
    value:
      otel_endpoint: 'https://otel.example.com'
      sampling_rate: 0.1
      tracing_enabled: true
      metrics_enabled: true
    enforcement: 'default'

Plain-text (insecure) collector endpoint​

For internal collectors that don't use TLS, for example on a private network, set insecure: true:

values.yaml
enterpriseConfig:
  telemetry:
    value:
      otel_endpoint: 'http://otel.internal.example.com:4318'
      insecure: true
      tracing_enabled: true
      metrics_enabled: true
    enforcement: 'enforced'

Next steps​