diff --git a/content/en/opentelemetry/instrument/api_support/go.md b/content/en/opentelemetry/instrument/api_support/go.md deleted file mode 100644 index 3c732923022..00000000000 --- a/content/en/opentelemetry/instrument/api_support/go.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Go Custom Instrumentation using the OpenTelemetry API ---- - -{{< include-markdown "/tracing/trace_collection/custom_instrumentation/go/otel/" >}} \ No newline at end of file diff --git a/content/en/opentelemetry/instrument/api_support/go/_index.md b/content/en/opentelemetry/instrument/api_support/go/_index.md new file mode 100644 index 00000000000..373706a6447 --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/go/_index.md @@ -0,0 +1,5 @@ +--- +title: Go +type: multi-code-lang +external_redirect: /opentelemetry/instrument/api_support/go/traces +--- diff --git a/content/en/opentelemetry/instrument/api_support/go/metrics.md b/content/en/opentelemetry/instrument/api_support/go/metrics.md new file mode 100644 index 00000000000..638c493d9c1 --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/go/metrics.md @@ -0,0 +1,50 @@ +--- +title: Go OpenTelemetry Metrics API Support +# Uncomment Metrics tab when Go metrics support is available +# code_lang: metrics +# type: multi-code-lang +# code_lang_weight: 1 +further_reading: + - link: opentelemetry/correlate/metrics_and_traces + tag: Documentation + text: Correlate OpenTelemetry Traces and Metrics +--- + +## Overview + +{{% otel-overview-exporter lang="Go" signal="Metrics" sdk_name="dd-trace-go" %}} + +**Note**: Go OpenTelemetry Metrics API support is not yet available. + +## Prerequisites + +- **Datadog SDK**: dd-trace-go version TBD. +- **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel metrics. + +## Setup + +*Documentation will be added when Go metrics support becomes available.* + +## Examples + +*Examples will be added when Go metrics support becomes available.* + +## Supported configuration + +*Configuration details will be added when Go metrics support becomes available.* + +For a complete list of all shared OTLP environment variables, see [OpenTelemetry Environment Variables Interoperability][1]. + +## Migrate from other setups + +*Migration guidance will be added when Go metrics support becomes available.* + +## Troubleshooting + +*Troubleshooting information will be added when Go metrics support becomes available.* + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /opentelemetry/config/environment_variable_support diff --git a/content/en/opentelemetry/instrument/api_support/go/traces.md b/content/en/opentelemetry/instrument/api_support/go/traces.md new file mode 100644 index 00000000000..a94304ea235 --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/go/traces.md @@ -0,0 +1,8 @@ +--- +title: Go OpenTelemetry Traces API Support +code_lang: traces +type: multi-code-lang +code_lang_weight: 0 +--- + +{{< include-markdown "/tracing/trace_collection/custom_instrumentation/go/otel/" >}} diff --git a/content/en/opentelemetry/instrument/api_support/php.md b/content/en/opentelemetry/instrument/api_support/php.md deleted file mode 100644 index f1439780cc9..00000000000 --- a/content/en/opentelemetry/instrument/api_support/php.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: PHP Custom Instrumentation using the OpenTelemetry API ---- - -{{< include-markdown "/tracing/trace_collection/custom_instrumentation/php/otel/" >}} \ No newline at end of file diff --git a/content/en/opentelemetry/instrument/api_support/php/_index.md b/content/en/opentelemetry/instrument/api_support/php/_index.md new file mode 100644 index 00000000000..ffc8ab27ff8 --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/php/_index.md @@ -0,0 +1,5 @@ +--- +title: PHP +type: multi-code-lang +external_redirect: /opentelemetry/instrument/api_support/php/traces +--- diff --git a/content/en/opentelemetry/instrument/api_support/php/metrics.md b/content/en/opentelemetry/instrument/api_support/php/metrics.md new file mode 100644 index 00000000000..b9c793f7463 --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/php/metrics.md @@ -0,0 +1,126 @@ +--- +title: PHP OpenTelemetry Metrics API Support +# Uncomment Metrics tab when PHP metrics support is available +# code_lang: metrics +# type: multi-code-lang +# code_lang_weight: 1 +further_reading: + - link: opentelemetry/correlate/metrics_and_traces + tag: Documentation + text: Correlate OpenTelemetry Traces and Metrics +--- + +## Overview + +{{% otel-overview-exporter lang="PHP" signal="Metrics" sdk_name="dd-trace-php" %}} + +**Note**: PHP OpenTelemetry Metrics API support is not yet available. + +## Prerequisites + +- **Datadog SDK**: dd-trace-php version 1.16.0 or later. +- **OpenTelemetry PHP SDK**: Version 1.0.0 or later (`open-telemetry/sdk`). +- **OpenTelemetry OTLP Exporter**: The OTLP exporter package (`open-telemetry/exporter-otlp`). +- **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel metrics. + +## Setup + +### 1. Install the required packages + +Follow these steps to enable OTel Metrics API support in your PHP application. + +1. Install the Datadog PHP tracer following the [official installation instructions][2]. + +2. Install the required OpenTelemetry packages: + +```sh +composer require open-telemetry/sdk +composer require open-telemetry/exporter-otlp +``` + +### 2. Enable OpenTelemetry Metrics + +Set the `DD_METRICS_OTEL_ENABLED` environment variable to enable OpenTelemetry Metrics support: + +```sh +export DD_METRICS_OTEL_ENABLED=true +``` + +Alternatively, set it in your `php.ini`: + +```php +datadog.metrics_otel_enabled = true +``` + +### 3. Configure your application: + +The Datadog SDK automatically configures the OpenTelemetry MeterProvider when your application loads. No additional code configuration is required. + +If your Datadog Agent is running on a non-default location, configure the endpoint: + +# Option 1: Using the Agent URL +```sh +export DD_TRACE_AGENT_URL=http://your-agent-host:8126 +``` + +# Option 2: Using the Agent host +```sh +export DD_AGENT_HOST=your-agent-host +``` + +The SDK automatically resolves the appropriate OTLP endpoint (port 4318 for HTTP, port 4317 for gRPC). + +## Examples + +### Create a counter + +This example uses the OTel Metrics API to create a counter that increments every time a request is processed: + +```php +use OpenTelemetry\API\Globals; + +// dd-trace-php automatically configures the MeterProvider +$meter = Globals::meterProvider()->getMeter('my-service'); +$counter = $meter->createCounter('requests', 'requests', 'Total number of requests'); +$counter->add(1, ['method' => 'GET', 'route' => '/api/users']); +``` + +## Supported configuration + +To enable this feature, you must set `DD_METRICS_OTEL_ENABLED=true` (or `datadog.metrics_otel_enabled = true` in php.ini). + +All OTLP exporter settings (such as endpoints, protocols, and timeouts), resource attributes, and temporality preferences are configured using a shared set of OpenTelemetry environment variables. + +For a complete list of all shared OTLP environment variables, see [OpenTelemetry Environment Variables Interoperability][1]. + +## Migrate from other setups + +### Existing OTel setup + +If you are using the OTel SDK with your own manual OTLP exporter configuration: + +1. Install the Datadog PHP tracer following the [official installation instructions][2]. +2. Remove any code that manually configures the OTLP exporter. The Datadog SDK handles this configuration automatically. +3. Set the `DD_METRICS_OTEL_ENABLED=true` environment variable. + +### Existing DogStatsD setup + +If you are currently using the Datadog DogStatsD client and want to migrate to the OpenTelemetry Metrics API, update your instrumentation code to use the OTel Meter API instead of StatsD client calls. + +## Troubleshooting + +{{% otel-api-troubleshooting signal="metrics" %}} + +- Verify OpenTelemetry SDK version. Version 1.0.0 or later is required. +- Ensure `open-telemetry/exporter-otlp` package is installed. +- Ensure `DD_METRICS_OTEL_ENABLED=true` is set before your application starts. +- Enable debug logging with `DD_TRACE_DEBUG=true` to see detailed logs. + +{{% /otel-api-troubleshooting %}} + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /opentelemetry/config/environment_variable_support +[2]: /tracing/trace_collection/dd_libraries/php/#install-the-extension \ No newline at end of file diff --git a/content/en/opentelemetry/instrument/api_support/php/traces.md b/content/en/opentelemetry/instrument/api_support/php/traces.md new file mode 100644 index 00000000000..4c8a8c9d21b --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/php/traces.md @@ -0,0 +1,8 @@ +--- +title: PHP OpenTelemetry Traces API Support +code_lang: traces +type: multi-code-lang +code_lang_weight: 0 +--- + +{{< include-markdown "/tracing/trace_collection/custom_instrumentation/php/otel/" >}} diff --git a/content/en/opentelemetry/instrument/api_support/rust.md b/content/en/opentelemetry/instrument/api_support/rust.md deleted file mode 100644 index 802a6c00e5c..00000000000 --- a/content/en/opentelemetry/instrument/api_support/rust.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Rust Custom Instrumentation using the OpenTelemetry API ---- - -{{< include-markdown "/tracing/trace_collection/custom_instrumentation/rust/" >}} \ No newline at end of file diff --git a/content/en/opentelemetry/instrument/api_support/rust/_index.md b/content/en/opentelemetry/instrument/api_support/rust/_index.md new file mode 100644 index 00000000000..c425f785915 --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/rust/_index.md @@ -0,0 +1,5 @@ +--- +title: Rust +type: multi-code-lang +external_redirect: /opentelemetry/instrument/api_support/rust/traces +--- diff --git a/content/en/opentelemetry/instrument/api_support/rust/metrics.md b/content/en/opentelemetry/instrument/api_support/rust/metrics.md new file mode 100644 index 00000000000..661f9662343 --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/rust/metrics.md @@ -0,0 +1,116 @@ +--- +title: Rust OpenTelemetry Metrics API Support +# Uncomment Metrics tab after dd-trace-rs v0.3.0 is released +# code_lang: metrics +# type: multi-code-lang +# code_lang_weight: 1 +further_reading: + - link: opentelemetry/correlate/metrics_and_traces + tag: Documentation + text: Correlate OpenTelemetry Traces and Metrics +--- + +## Overview + +{{% otel-overview-exporter lang="Rust" signal="Metrics" sdk_name="datadog-opentelemetry" %}} + +**Note**: Metrics support will be available in datadog-opentelemetry v0.3.0. + +## Prerequisites + +- **Datadog SDK**: `datadog-opentelemetry` crate version 0.3.0 or later. +- **Rust**: MSRV 1.84 or later. +- **An OTLP-compatible destination**: You must have a destination (Agent or Collector) listening on ports 4317 (gRPC) or 4318 (HTTP) to receive OTel metrics. + +## Setup + +Follow these steps to enable OTel Metrics API support in your Rust application. + +1. Add the Datadog SDK to your Cargo.toml: + ```toml + [dependencies] + datadog-opentelemetry = { version = "0.3.0" } + opentelemetry = { version = "0.31", features = ["metrics"] } + ``` + +2. Enable OTel metrics by setting the following environment variable: + ```sh + export DD_METRICS_OTEL_ENABLED=true + ``` + +3. Configure your application: + ```rust + // Initialize metrics with default configuration + let meter_provider = datadog_opentelemetry::metrics().init(); + + // Your application code here... + + // Shutdown to flush remaining metrics + meter_provider.shutdown().unwrap(); + ``` + +## Examples + +You can use the standard OpenTelemetry API packages to create custom metrics. + +### Create a counter + +This example uses the OTel Metrics API to create a counter that increments every time an item is processed: + +```rust +use opentelemetry::global; +use opentelemetry::metrics::Counter; +use opentelemetry::KeyValue; + +// datadog-opentelemetry automatically configures the MeterProvider +let meter = global::meter("my-service"); +let counter: Counter = meter.u64_counter("requests").build(); +counter.add(1, &[KeyValue::new("method", "GET")]); +``` + +## Supported configuration + +To enable this feature, you must set `DD_METRICS_OTEL_ENABLED=true`. + +All OTLP exporter settings (such as endpoints, protocols, and timeouts), resource attributes, and temporality preferences are configured using a shared set of OpenTelemetry environment variables. + +### Transport Features + +The default feature includes gRPC transport. Additional transport options: + +- For gRPC transport: `features = ["metrics-grpc"]` (default) +- For HTTP transport: `features = ["metrics-http"]` + +**Note**: HTTP/JSON protocol is not supported. Use `grpc` or `http/protobuf` protocols only. + +For a complete list of all shared OTLP environment variables, see [OpenTelemetry Environment Variables Interoperability][1]. + +## Migrate from other setups + +### Existing OTel setup + +If you are using the OTel SDK with your own manual OTLP exporter configuration: + +1. Add the Datadog SDK (`datadog-opentelemetry`) to your project and enable its instrumentation. +2. Remove any code that manually configures the `OTLPMetricsExporter`. The Datadog SDK handles this configuration automatically. +3. Set the `DD_METRICS_OTEL_ENABLED=true` environment variable. + +### Existing DogStatsD setup + +If you are currently using the Datadog DogStatsD client and want to migrate to the OpenTelemetry Metrics API, you need to update your instrumentation code. The main difference is that OTel metrics are configured using environment variables rather than code, and you create `Instrument` objects first. + +**Important**: Runtime and trace metrics continue to be submitted using StatsD. Only custom metrics created through the OpenTelemetry Metrics API are sent using OTLP. The `datadog-opentelemetry` implementation supports exporting OTLP metrics exclusively to a Datadog Agent or OpenTelemetry Collector. Multiple exporters are not supported. + +## Troubleshooting + +{{% otel-api-troubleshooting signal="metrics" %}} +- Verify transport features are enabled. Ensure `metrics-grpc` or `metrics-http` feature is enabled in your Cargo.toml depending on your protocol choice. +- Check protocol configuration. Only `grpc` and `http/protobuf` protocols are supported. HTTP/JSON is not supported. +- Ensure `DD_METRICS_OTEL_ENABLED=true` is set before initializing the meter provider. +{{% /otel-api-troubleshooting %}} + +## Further reading + +{{< partial name="whats-next/whats-next.html" >}} + +[1]: /opentelemetry/config/environment_variable_support diff --git a/content/en/opentelemetry/instrument/api_support/rust/traces.md b/content/en/opentelemetry/instrument/api_support/rust/traces.md new file mode 100644 index 00000000000..b34e1a7507e --- /dev/null +++ b/content/en/opentelemetry/instrument/api_support/rust/traces.md @@ -0,0 +1,8 @@ +--- +title: Rust OpenTelemetry Traces API Support +code_lang: traces +type: multi-code-lang +code_lang_weight: 0 +--- + +{{< include-markdown "/tracing/trace_collection/custom_instrumentation/rust/" >}}