Compute histogram summaries

Ingest histograms directly

Starting with Dynatrace version 1.300, histogram ingestion is supported directly via OTLP ingest API. Consequently, it's not required to use Collector as a workaround. Dynatrace recommends ingesting histograms directly without additional data manipulation.

The following configuration example shows how to use the Collector to compute and ingest summaries of histogram buckets, such as the overall sum of all values in the bucket and their total count.

Prerequisites

One of the following Collector distributions with the transform and filter processors:
- The Dynatrace Collector
- OpenTelemetry Contrib
- A custom Builder version
The Dynatrace API endpoint URL to which the data should be exported
An API token with the relevant access scope (only required for SaaS and ActiveGate)

Demo configuration

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  transform:
    metric_statements:
      - context: metric
        statements:
          # Get count from the histogram. The new metric name will be <histogram_name>_count
          - extract_count_metric(true) where type == METRIC_DATA_TYPE_HISTOGRAM

          # Get sum from the histogram. The new metric name will be <histogram_name>_sum
          - extract_sum_metric(true) where type == METRIC_DATA_TYPE_HISTOGRAM
          # convert the <histogram_name>_sum metrics to gauges.
          - convert_sum_to_gauge() where IsMatch(name, ".*_sum")

  filter:
    metrics:
      metric:
        # Drop metrics of type histogram. The _count and _sum metrics will still be exported.
        - type == METRIC_DATA_TYPE_HISTOGRAM

exporters:
  otlphttp:
    endpoint: ${env:DT_ENDPOINT}
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [transform,filter]
      exporters: [otlphttp]

Configuration validation

Validate your settings to avoid any configuration issues.

Components

For our configuration, we configure the following components.

Receivers

Under receivers, we specify the standard otlp receiver as active receiver component for our Collector instance and configure it to accept OTLP requests on gRPC and HTTP.

Processors

Under processors, we configure the following two processor instances:

transform, to compute the desired sum and count values of the histograms:
- We first use the function extract_count_metric to compute the number of values in each histogram bucket.
- Then, we use the function extract_sum_metric to compute the total sum of all of its values and convert it to a gauge using convert_sum_to_gauge.
filter, to drop the existing histogram buckets (based on type) and avoid histogram-related error messages.

With this configuration, the Collector drops histogram metrics and creates in their place two new metrics for the sum and item count of each respective histogram.

Exporters

Under exporters, we specify the default otlphttp exporter and configure it with our Dynatrace API URL and the required authentication token.

For this purpose, we set the following two environment variables and reference them in the configuration values for endpoint and Authorization:

DT_ENDPOINT contains the base URL of the Dynatrace API endpoint (for example, https://{your-environment-id}.live.dynatrace.com/api/v2/otlp)
DT_API_TOKEN contains the API token

Service pipelines

Under service, we assemble our receiver and exporter objects into a metric pipeline and enable the two processors by referencing them under processors.

Limits and limitations

Metrics are ingested using the OpenTelemetry protocol (OTLP) via the Dynatrace OTLP API and are subject to the API's limits and restrictions. For more information see: