> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Signalfx

> OpenTelemetry exporter for Signalfx

# Signalfx Exporter

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@dmitryax](https://github.com/dmitryax), [@crobert-1](https://github.com/crobert-1)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-beta-blue) ![Metrics](https://img.shields.io/badge/metrics-beta-green) ![Traces](https://img.shields.io/badge/traces-deprecated-orange)

## Overview

This exporter can be used to send metrics, events, and trace correlation to SignalFx.

Apart from metrics, the exporter is also capable of sending metric metadata
(properties and tags) to SignalFx. Currently, only metric metadata updates from
the [k8s\_cluster receiver](../../receiver/k8sclusterreceiver/README.md) are
supported.

## Metrics Configuration

The following configuration options are required:

* `access_token` (no default): The access token is the [authentication token
  provided by Splunk Observability
  Cloud](https://help.splunk.com/en/splunk-observability-cloud/administer/authentication-and-security/authentication-tokens/manage-usage-with-access-tokens).
  The access token can be obtained from the web app.
* Either `realm` or both `api_url` and `ingest_url`. Both `api_url` and
  `ingest_url` take precedence over `realm`.
  * `realm` (no default): SignalFx realm where the data will be received.
  * `api_url` (no default): Destination to which [properties and
    tags](https://help.splunk.com/en/splunk-observability-cloud/data-tools/metric-finder-and-metadata-catalogue)
    are sent. If `realm` is set, this option is derived and will be
    `https://api.{realm}.observability.splunkcloud.com`. If a value is explicitly set, the
    value of `realm` will not be used in determining `api_url`. The explicit
    value will be used instead.
  * `ingest_url` (no default): Destination where SignalFx metrics are sent. If
    `realm` is set, this option is derived and will be
    `https://ingest.{realm}.observability.splunkcloud.com`. If a value is
    explicitly set, the value of `realm` will not be used in determining
    `ingest_url`. The explicit value will be used instead. The exporter will
    automatically append the appropriate path: "/v2/datapoint" for metrics,
    and "/v2/event" for events.

The following configuration options can also be configured:

* `access_token_passthrough`: (default = `true`) Whether to use
  `"com.splunk.signalfx.access_token"` metric resource attribute, if any, as the
  SignalFx access token.  In either case this attribute will be dropped during
  final translation, in this exporter only.  Intended to be used in tandem with
  identical configuration option for [SignalFx
  receiver](../../receiver/signalfxreceiver/README.md) to preserve datapoint
  origin for only this exporter, as others will reveal the organization access token
  by not filtering the attribute.
* `exclude_metrics`: List of metric filters that will determine metrics to be
  excluded from sending to Signalfx backend. The filtering is applied after the default
  translations controlled by `disable_default_translation_rules` option.
  See in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/testdata/config.yaml) for examples. Apart from the values explicitly
  provided via this option, by default, [default metrics](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/internal/translation/default_metrics.yaml) are
  also appended to this list. Setting this option to `[]` will override all the default
  excludes.
* `include_metrics`: List of filters to override exclusion of any metrics.
  This option can be used to included metrics that are otherwise dropped by
  default. See [default metrics](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/internal/translation/default_metrics.yaml) for a list of metrics
  that are dropped by default. For example, the following configuration can be
  used to send through some of that are dropped by default.
  ```yaml theme={null}
  include_metrics:
    # When sending in translated metrics.
    - metric_names: [cpu.interrupt, cpu.user, cpu.system]
    # When sending in metrics in OTel convention.
    - metric_name: system.cpu.time
      dimensions:
        state: [interrupt, user, system]
  ```
* `log_data_points` (default = `false`): If the log level is set to `debug`
  and this is true, all datapoints dispatched to Splunk Observability Cloud will be logged
* `log_dimension_updates` (default = `false`): Whether or not to log dimension
  updates.
* `disable_default_translation_rules` (default = `false`): Disable default translation
  of the OTel metrics to a SignalFx compatible format. The default translation rules are
  defined in [`internal/translation/default_translation_rules.yaml`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/internal/translation/default_translation_rules.yaml).
* `timeout` (default = 10s): Amount of time to wait for a send operation to
  complete.
* `http2_read_idle_timeout` (default = 10s): Send a ping frame for a health check if the connection has been idle for the configured value.
  0s means http/2 health check will be disabled.
* `http2_ping_timeout` (default = 10s): Triggered by `http2_read_idle_timeout`; When there's no response to the ping within the configured value,
  the connection will be closed. If this value is set to 0, it will default to 15s.
* `headers` (no default): Headers to pass in the payload.
* `max_idle_conns` (default = 100): The maximum idle HTTP connections the client can keep open.
* `max_idle_conns_per_host` (default = 100): The maximum idle HTTP connections the client can keep open per host.
* `idle_conn_timeout` (default = 30s): The maximum amount of time an idle connection will remain open before closing itself.
* More HTTP settings are available, see
  [HTTP settings](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/confighttp/README.md).
* `sync_host_metadata`: Defines whether the exporter should scrape host metadata
  and send it as property updates to SignalFx backend. Disabled by default.
  IMPORTANT: Host metadata synchronization relies on `resource_detection`
  processor. If this option is enabled make sure that `resource_detection`
  processor is enabled in the pipeline with one of the cloud provider detectors
  or environment variable detector setting a unique value to `host.id` attribute
  within your k8s cluster. And keep `override=true` in resource\_detection config.
* `root_path`: Used by the host metadata to identify the root filesystem.
  This is needed when running in a containerized environment and the host root
  filesystem is not `/`. Example: if the root filesystem is mounted under `/hostfs`, set
  `root_path` to `/hostfs`.
  Note: all components using `root_path` must have the same value; this currently applies
  to hostmetrics receiver and signalfx exporter.
* `exclude_properties`: A list of property filters to limit dimension update content.
  Property filters can contain any number of the following fields, supporting (negated)
  string literals, re2 `/regex/`, and [glob](https://github.com/gobwas/glob) syntax values:
  `dimension_name`, `dimension_value`, `property_name`, and `property_value`. For any field
  not expressly configured for each filter object, a default catch-all value of `/^.*$/` is used
  to allow each specified field to require a match for the filter to take effect:
  ```yaml theme={null}
  # will filter all 'k8s.workload.name' properties from 'k8s.pod.uid' dimension updates:
  exclude_properties:
    - dimension_name: k8s.pod.uid
      property_name: k8s.workload.name
  ```
* `dimension_client`: Contains options controlling the dimension update client configuration used for metadata updates.
  * `max_buffered:` (default = 10,000): The buffer size for queued dimension updates.
  * `send_delay` (default = 10s): The time to wait between dimension updates for a given dimension.
  * `max_idle_conns` (default = 20): The maximum idle HTTP connections the client can keep open.
  * `max_idle_conns_per_host` (default = 20): The maximum idle HTTP connections the client can keep open per host.
  * `max_conns_per_host` (default = 20): The maximum total number of connections the client can keep open per host.
  * `idle_conn_timeout` (default = 30s): The maximum amount of time an idle connection will remain open before closing itself.
  * `timeout` (default = 10s): Amount of time to wait for the dimension HTTP request to complete.
  * `drop_tags` (default = false): Flag that indicates whether to drop the tags from the metadata sent to Splunk Observability Cloud by the exporter.
* `nonalphanumeric_dimension_chars`: (default = `"_-."`) A string of characters
  that are allowed to be used as a dimension key in addition to alphanumeric
  characters. Each nonalphanumeric dimension key character that isn't in this string
  will be replaced with a `_`.
* `ingest_tls`: (no default) exposes a list of TLS settings to establish a secure connection with signafx receiver configured on another collector instance.
  * `ca_file` needs to be set if the exporter's `ingest_url` is pointing to a signalfx receiver
    with TLS enabled and using a self-signed certificate where its CA is not loaded in the system cert pool.
    Full list of TLS options can be found in the configtls [README](https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configtls#client-configuration)
    The following example instructs the signalfx exporter ingest client to use a custom `ca_file` to verify the server certificate.
  ```yaml theme={null}
  ingest_tls:
      ca_file: "/etc/opt/certs/ca.pem"
  ```
* `api_tls`: (no default) exposes a list of TLS settings to establish a secure connection with http\_forwarder extension configured on another collector instance.
  * `ca_file` needs to be set if the exporter's `api_url` is pointing to a http\_forwarder extension
    with TLS enabled and using a self-signed certificate where its CA is not loaded in the system cert pool.
    Full list of TLS options can be found in the configtls [README](https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/configtls#client-configuration)
    The following example instructs the signalfx exporter api client to use a custom `ca_file` to verify the server certificate.
  ```yaml theme={null}
  api_tls:
      ca_file: "/etc/opt/certs/ca.pem"
  ```
* `drop_histogram_buckets`:  (default = `false`) if set to true, histogram buckets will not be translated into datapoints with `_bucket` suffix but will be dropped instead, only datapoints with `_sum`, `_count`, `_min` (optional) and `_max` (optional) suffixes will be sent. Please note that this option does not apply to histograms sent in OTLP format with `send_otlp_histograms` enabled.
* `send_otlp_histograms`: (default: `false`) if set to true, any histogram metrics receiver by the exporter will be sent to Splunk Observability backend in OTLP format without conversion to SignalFx format. This can only be enabled if the Splunk Observability environment (realm) has the new Histograms feature rolled out. Please note that histograms sent in OTLP format do not apply to the exporter configurations `include_metrics` and `exclude_metrics`.
  In addition, this exporter offers queued retry which is enabled by default.
  For more information, see the queued retry options in the [exporter documentation](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/exporterhelper/README.md).

## DEPRECATED: Traces Configuration (correlation only)

:warning: *Note that traces must still be sent to Splunk Observability via a separate trace exporter.*

When traces are sent to the signalfx exporter it correlates traces to metrics. When a new service or environment is
seen it associates the source (e.g. host or pod) to that service or environment in SignalFx. Metrics can then be
filtered based on that trace service and environment (`sf_service` and `sf_environment`).

One of `realm` and `api_url` are required.

* `access_token` (required, no default): The access token is the authentication token
  provided by SignalFx.
* `realm` (no default): SignalFx realm where the data will be received.
* `api_url` (default = `https://api.{realm}.observability.splunkcloud.com/`): Destination to which correlation updates
  are sent. If a value is explicitly set, the value of `realm` will not be used in determining `api_url`.
  The explicit value will be used instead.
* `correlation` Contains options controlling the syncing of service and environment properties onto dimensions.
  * `endpoint` (required, default = `api_url` or `https://api.{realm}.observability.splunkcloud.com/`): This is the base URL for API requests (e.g. `https://api.us0.observability.splunkcloud.com`).
  * `timeout` (default = 5s): Is the timeout for every attempt to send data to the backend.
  * `stale_service_timeout` (default = 5 minutes): How long to wait after a span's service name is last seen before uncorrelating it.
  * `max_requests` (default = 20): Max HTTP requests to be made in parallel.
  * `max_buffered` (default = 10,000): Max number of correlation updates that can be buffered before updates are dropped.
  * `max_retries` (default = 2): Max number of retries that will be made for failed correlation updates.
  * `log_updates` (default = false): Whether or not to log correlation updates to dimensions (at `DEBUG` level).
  * `retry_delay` (default = 30 seconds): How long to wait between retries.
  * `cleanup_interval` (default = 1 minute): How frequently to purge duplicate requests.
  * `sync_attributes` (default = `{"k8s.pod.uid": "k8s.pod.uid", "container.id": "container.id"}`) Map containing key of the attribute to read from spans to sync to dimensions specified as the value.

## Default Metric Filters

[List of metrics excluded by default](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/internal/translation/default_metrics.yaml)

Some OpenTelemetry receivers may send metrics that SignalFx considers to be categorized as custom metrics. In order to prevent unwanted overage usage due to custom metrics from these receivers, the SignalFx exporter has a [set of metrics excluded by default](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/internal/translation/default_metrics.yaml). Some exclusion rules use regex to exclude multiple metric names. Some metrics are only excluded if specific resource labels (dimensions) are present. If the default translation rules are enabled and match an exclusion rule, the exclusion takes precedence. Users may configure the SignalFx exporter's `include_metrics` config option to override the any of the default exclusions, as `include_metrics` will always take precedence over any exclusions. An example of `include_metrics` is shown below.

```
exporters:
  signalfx:
    include_metrics:
      - metric_names: [cpu.interrupt, cpu.user, cpu.system]
      - metric_name: system.cpu.time
        dimensions:
          state: [interrupt, user, system]
```

## Translation Rules and Metric Transformations

The default translation rules defined in [`translation/default_translation_rules.yaml`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/internal/translation/default_translation_rules.yaml) are used by the SignalFx exporter
to help ensure compatibility with custom charts and dashboards when using the OpenTelemetry Collector.
The default rules will create the following aggregated metrics from the [`hostmetrics` receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/README.md):

* cpu.idle
* cpu.interrupt
* cpu.nice
* cpu.num\_processors
* cpu.softirq
* cpu.steal
* cpu.system
* cpu.user
* cpu.utilization
* cpu.wait
* disk.summary\_utilization
* disk.utilization
* disk\_ops.pending
* disk\_ops.total
* memory.total
* memory.utilization
* network.total
* process.cpu\_time\_seconds
* system.disk.io.total
* system.disk.operations.total
* system.network.io.total
* system.network.packets.total
* vmpage\_io.memory.in
* vmpage\_io.memory.out
* vmpage\_io.swap.in
* vmpage\_io.swap.out

## Example Config

```yaml theme={null}
exporters:
  signalfx:
    access_token: <replace_with_actual_access_token>
    access_token_passthrough: true
    headers:
      added-entry: "added value"
      dot.test: test
    realm: us1
    timeout: 5s
    max_idle_conns: 80
    sending_queue:
      batch:
```

> :warning: When enabling the SignalFx receiver or exporter, configure both the `metrics` and `logs` pipelines.

```yaml theme={null}
service:
  pipelines:
    metrics:
      receivers: [signalfx]
      processors: [memory_limiter]
      exporters: [signalfx]
    logs:
      receivers: [signalfx]
      processors: [memory_limiter]
      exporters: [signalfx]
    traces:
      receivers: [zipkin]
      processors: []
      exporters: [signalfx]
```

The full list of settings exposed for this exporter are documented in [config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/config.go)
with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/signalfxexporter/testdata/config.yaml).

This exporter also offers [proxy support](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter#proxy-support).

## Advanced Configuration

Several helper files are leveraged to provide additional capabilities automatically:

* [HTTP settings](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/confighttp/README.md)
* [TLS and mTLS settings](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md)
* [Queuing, retry and timeout settings](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/exporterhelper/README.md)

## Configuration

### Example Configuration

```yaml theme={null}
signalfx:
  access_token: testToken
  realm: ap0
signalfx/allsettings:
  access_token: testToken
  realm: "us1"
  timeout: 2s
  max_idle_conns: 70
  max_idle_conns_per_host: 70
  sending_queue:
    enabled: true
    num_consumers: 2
    queue_size: 10
  retry_on_failure:
    enabled: true
    initial_interval: 10s
    max_interval: 60s
    max_elapsed_time: 10m
  headers:
    added-entry: "added value"
    dot.test: test
  access_token_passthrough: false
  default_properties:
    foo: bar
    _index: baz
  exclude_metrics:
    - metric_name: metric1
    - metric_names: [metric2, metric3]
    - metric_name: metric4
      dimensions:
        dimension_key: dimension_val
    - metric_name: metric5
      dimensions:
        dimension_key: [dimension_val1, dimension_val2]
    # Apart from exact matches these fields also take regex and globs
    - metric_name: /cpu\..*/
    - metric_names: [cpu.util*, memory.util*]
    - metric_name: cpu.utilization
      dimensions:
        container_name: /^[A-Z][A-Z]$/
  include_metrics:
    - metric_name: metric1
    - metric_names: [metric2, metric3]
  log_dimension_updates: true
  dimension_client:
    max_buffered: 1
    send_delay: 1h
    max_idle_conns: 100
    max_idle_conns_per_host: 10
    max_conns_per_host: 10000
    idle_conn_timeout: 2h
    timeout: 20s
  exclude_properties:
    - property_name: globbed*
    - property_value: '!globbed*value'
    - dimension_name: globbed*
    - dimension_value: '!globbed*value'
    - property_name: globbed*
      property_value: '!globbed*value'
      dimension_name: globbed*
      dimension_value: '!globbed*value'
  send_otlp_histograms: true
```

***

*Last generated: 2026-07-06*