feat(otel): add support for otel metrics #5021
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,12 +1,14 @@ | ||
| # OpenTelemetry | ||
|
|
||
| **Supported OpenTelemetry features**: | ||
|
|
||
| | Type | Documentation | datadog version | Gem version support | | ||
| | ------------- | ---------------------------------------------------- | --------------- | ------------------- | | ||
| | Tracing | https://github.com/open-telemetry/opentelemetry-ruby | 1.9.0+ | >= 1.1.0 | | ||
| | Metrics SDK | https://rubygems.org/gems/opentelemetry-metrics-sdk | 2.25.0+ | >= 0.8 | | ||
| | OTLP Metrics Exporter | https://rubygems.org/gems/opentelemetry-exporter-otlp-metrics | 2.25.0+ | >= 0.4 | | ||
|
||
|
|
||
| ## Configuring OpenTelemetry Tracing | ||
|
|
||
| 1. Add the `datadog` gem to your Gemfile: | ||
|
|
||
|
|
@@ -44,6 +46,55 @@ | |
|
|
||
| [Integration instrumentations](#integration-instrumentation) and OpenTelemetry [Automatic instrumentations](https://opentelemetry.io/docs/instrumentation/ruby/automatic/) are also supported. | ||
|
|
||
| ## Configuring OpenTelemetry Metrics | ||
|
|
||
| 1. Add required gems to your Gemfile: | ||
mabdinur marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ```ruby | ||
| gem 'datadog' | ||
| gem 'opentelemetry-metrics-sdk', '~> 0.8' | ||
| gem 'opentelemetry-exporter-otlp-metrics', '~> 0.4' | ||
| ``` | ||
|
|
||
| 1. Install gems with `bundle install` | ||
mabdinur marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 1. Enable metrics export: | ||
|
|
||
| ```ruby | ||
| # Set environment variable before initializing metrics support | ||
| ENV['DD_METRICS_OTEL_ENABLED'] = 'true' | ||
| require 'opentelemetry/sdk' | ||
| require 'opentelemetry-metrics-sdk' | ||
| require 'opentelemetry/exporter/otlp_metrics' | ||
| require 'datadog/opentelemetry' | ||
|
Comment on lines
64
to
67
Member
There was a problem hiding this comment. Have you considered turning these 5 lines into a That way customers would only need to copy-paste the simpler require :)
Contributor
Author
There was a problem hiding this comment. Actually only opentelemetry/sdk and datadog/opentelemetry are required. We do not need to import |
||
| # IMPORTANT: Call Datadog.configure before OpenTelemetry::SDK.configure | ||
| # and keep both in the same file to ensure proper initialization order. | ||
| Datadog.configure do |c| | ||
| # Configure Datadog settings here | ||
| end | ||
| # Initialize OpenTelemetry SDK (required for metrics) | ||
| OpenTelemetry::SDK.configure | ||
| ``` | ||
|
|
||
|
Member
There was a problem hiding this comment. Does ENV['DD_METRICS_OTEL_ENABLED'] = 'true'
require 'opentelemetry/sdk'
require 'opentelemetry-metrics-sdk'
require 'opentelemetry/exporter/otlp_metrics'
require 'datadog/opentelemetry'
require 'opentelemetry/metrics'
provider = OpenTelemetry.meter_provider
meter = provider.meter('my-app')
counter = meter.create_counter('requests')
counter.add(1)
Contributor
Author
There was a problem hiding this comment. OpenTelemetry::SDK.configure is required here. Otherwise we will get the NoopMeterProvider. Good catch. I will fix these docs |
||
| 1. Use the [OpenTelemetry Metrics API](https://opentelemetry.io/docs/languages/ruby/instrumentation/#metrics) to create and record metrics. | ||
|
|
||
| **Note:** Call `Datadog.configure` before `OpenTelemetry::SDK.configure` and keep both in the same file. Configuration changes require calling `OpenTelemetry::SDK.configure` again to take effect. | ||
|
|
||
| **Configuration Options:** | ||
|
|
||
| - `DD_METRICS_OTEL_ENABLED` - Enable metrics export (default: false) | ||
| - `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` - Protocol: `http/protobuf` (default); `grpc` and `http/json` are not yet supported. | ||
| - `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` - Custom endpoint (defaults to the Datadog agent otlp endpoint) | ||
| - `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` - `delta` (default) or `cumulative` | ||
|
Member
There was a problem hiding this comment. @mabdinur does
Member
There was a problem hiding this comment.
Just to confirm, does it? If it doesn't them we have to document it here.
Contributor
Author
There was a problem hiding this comment. Cumulative is support, it just requires additional processing in the agent/collector. We have this doc that discusses it: https://docs.datadoghq.com/opentelemetry/guide/otlp_delta_temporality/?tab=python. |
||
| - `OTEL_METRIC_EXPORT_INTERVAL` - Export interval in milliseconds (default: 10000) | ||
|
|
||
| [General OTLP settings](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) (`OTEL_EXPORTER_OTLP_*`) serve as defaults if metrics-specific settings are not provided. | ||
|
|
||
| **Note:** Minimum `opentelemetry-metrics-sdk` is v0.8.0 (contains critical bug fixes). Minimum `opentelemetry-exporter-otlp-metrics` is v0.4.0. Use the latest versions for best support. If you spot any issue with the OpenTelemetry API affecting the `datadog` gem, [please do open a GitHub issue](https://github.com/DataDog/dd-trace-rb/issues). | ||
|
|
||
|
|
||
| ## Limitations | ||
|
|
||
| There are a few limitations to OpenTelemetry Tracing when the APM integration is activated: | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where is
time_in_nanosecondsneeded? I can't find it in this PR.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's defined in opentelemetry-common and used in the opentelemetry metrics sdk: https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-ruby%20time_in_nanoseconds&type=code. It's not directly used in our library.
This is just note for us so we do not install incompatible opentelemetry libraries.