From 385b88322b950384fcbdb13462a6bdec8ccc755a Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 13 May 2025 10:49:16 +0200 Subject: [PATCH 01/14] Fix issues --- docs/reference/edot-sdks/dotnet/setup/index.md | 1 - docs/reference/edot-sdks/java/migration.md | 2 +- docs/reference/edot-sdks/nodejs/configuration.md | 2 +- docs/reference/edot-sdks/nodejs/migration.md | 2 +- docs/reference/edot-sdks/nodejs/setup/index.md | 2 +- docs/reference/edot-sdks/nodejs/setup/k8s.md | 4 ++-- docs/reference/edot-sdks/nodejs/troubleshooting.md | 2 +- docs/reference/edot-sdks/php/index.md | 2 +- docs/reference/edot-sdks/php/migration.md | 4 ++-- docs/reference/edot-sdks/php/setup/index.md | 4 ++-- docs/reference/edot-sdks/php/supported-technologies.md | 6 +++--- docs/reference/edot-sdks/php/troubleshooting.md | 8 ++++---- docs/reference/quickstart/serverless/k8s.md | 2 +- docs/reference/use-cases/kubernetes/customization.md | 2 +- .../use-cases/kubernetes/prerequisites-compatibility.md | 2 +- 15 files changed, 22 insertions(+), 23 deletions(-) diff --git a/docs/reference/edot-sdks/dotnet/setup/index.md b/docs/reference/edot-sdks/dotnet/setup/index.md index 8040c026..1bf725db 100644 --- a/docs/reference/edot-sdks/dotnet/setup/index.md +++ b/docs/reference/edot-sdks/dotnet/setup/index.md @@ -128,7 +128,6 @@ builder.AddElasticOpenTelemetry(b => b .ConfigureResource(r => r.AddService("MyAppName"))); ``` -{: .note } The preceding code requires two additional `using` directives: ```csharp diff --git a/docs/reference/edot-sdks/java/migration.md b/docs/reference/edot-sdks/java/migration.md index 21fb04df..d6e36d5b 100644 --- a/docs/reference/edot-sdks/java/migration.md +++ b/docs/reference/edot-sdks/java/migration.md @@ -74,7 +74,7 @@ By default, micrometer instrumentation is disabled and won't capture metrics, en - for [Annotation API](https://www.elastic.co/guide/en/apm/agent/java/current/public-api.html#api-annotation) see [OpenTelemetry Annotations](https://opentelemetry.io/docs/zero-code/java/agent/annotations/). - for [Transaction API](https://www.elastic.co/guide/en/apm/agent/java/current/public-api.html#api-transaction) see [OpenTelemetry API](https://opentelemetry.io/docs/zero-code/java/agent/api/). - :::note + :::{note} Migration of application code using these APIs and annotations is _not strictly required_ when deploying the EDOT agent. If not migrated, the spans, transactions and metrics that were previously explicitly created with those custom API calls and annotations, will no longer be generated. The broader OpenTelemetry instrumentation coverage may replace the need for some or all of these custom code changes. ::: 1. **Replace configuration options** using the [Reference](#option-reference) below, see [Configuration](./configuration.md) for ways to provide those. diff --git a/docs/reference/edot-sdks/nodejs/configuration.md b/docs/reference/edot-sdks/nodejs/configuration.md index d206b020..f8f6180a 100644 --- a/docs/reference/edot-sdks/nodejs/configuration.md +++ b/docs/reference/edot-sdks/nodejs/configuration.md @@ -37,7 +37,7 @@ export OTEL_SERVICE_NAME=my-app This section attempts to list all environment variables that can be used to configure EDOT Node.js. Some settings also have a section below discussing behavior that is interesting and/or specific to EDOT Node.js. -:::warning +:::{warning} The behavior of `OTEL_` environment variables are typically defined by upstream OpenTelemetry dependencies of EDOT Node.js. In some cases, these dependencies have a "development" status (`0.x` versions). This means that their behavior can be broken in a minor release of EDOT Node.js. ::: diff --git a/docs/reference/edot-sdks/nodejs/migration.md b/docs/reference/edot-sdks/nodejs/migration.md index 8eca69f2..7563b24c 100644 --- a/docs/reference/edot-sdks/nodejs/migration.md +++ b/docs/reference/edot-sdks/nodejs/migration.md @@ -99,7 +99,7 @@ The Elastic APM Node.js agent [`secretToken`](https://www.elastic.co/guide/en/ap For example: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token"`. -:::note +:::{note} Secret token usage is discouraged and Elastic recomends the usage of API keys for authentication. ::: diff --git a/docs/reference/edot-sdks/nodejs/setup/index.md b/docs/reference/edot-sdks/nodejs/setup/index.md index 1c568cd1..261bf982 100644 --- a/docs/reference/edot-sdks/nodejs/setup/index.md +++ b/docs/reference/edot-sdks/nodejs/setup/index.md @@ -60,7 +60,7 @@ To configure EDOT Node.js, as a typical minimum you will need: * `OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of HTTP headers used for exporting data, typically used to set the `Authorization` header with auth information. **Get an `ELASTIC_API_KEY` as described in the [EDOT Quickstart pages](../../../quickstart/index.md) and set this to `"Authorization=ApiKey ELASTIC_API_KEY"`.** * `OTEL_SERVICE_NAME`: The name of your service, used to distinguish telemetry data from other services in your system. If not set, it will default to `unknown_service:node`. -:::note +:::{note} In some environments, for example in some Kubernetes setups, a *local* OpenTelemetry Collector (e.g. EDOT Collector) is deployed with an endpoint of `http://localhost:4318`. This is the default exporter endpoint used by EDOT Node.js. In this case the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable does not need to be set. ::: diff --git a/docs/reference/edot-sdks/nodejs/setup/k8s.md b/docs/reference/edot-sdks/nodejs/setup/k8s.md index e6a39db7..ef773926 100644 --- a/docs/reference/edot-sdks/nodejs/setup/k8s.md +++ b/docs/reference/edot-sdks/nodejs/setup/k8s.md @@ -39,7 +39,7 @@ For this example, we assume the application you're instrumenting is a deployment elastic-instrumentation 107s http://opentelemetry-kube-stack-daemon-collector.opentelemetry-operator-system.svc.cluster.local:4318 ``` - :::note + :::{note} If your `Instrumentation` object has a different name or is created in a different namespace, you will have to adapt the annotation value in the next step. ::: @@ -153,7 +153,7 @@ For this example, we assume the application you're instrumenting is a deployment - The application shows transactions and metrics. - :::note + :::{note} You may need to generate traffic to your application to see spans and metrics. ::: diff --git a/docs/reference/edot-sdks/nodejs/troubleshooting.md b/docs/reference/edot-sdks/nodejs/troubleshooting.md index 50b86271..8c490fdf 100644 --- a/docs/reference/edot-sdks/nodejs/troubleshooting.md +++ b/docs/reference/edot-sdks/nodejs/troubleshooting.md @@ -124,7 +124,7 @@ When opening an issue: 2. **Describe your application/service/system architecture** as accurately as possible. 3. Include as much **[diagnostic log output](#sdk-diagnostic-logs)** as possible. -:::warning +:::{warning} Though an effort is made to avoid it, verbose/debug diagnostic logs **can include sensitive information**. Therefore it is **not** recommended that the full log is included in public forums or GitHub issues. (This is less of a concern for private Elastic customer support.) ::: diff --git a/docs/reference/edot-sdks/php/index.md b/docs/reference/edot-sdks/php/index.md index a6bb490f..eb213698 100644 --- a/docs/reference/edot-sdks/php/index.md +++ b/docs/reference/edot-sdks/php/index.md @@ -19,7 +19,7 @@ Use EDOT PHP to start the OpenTelemetry SDK with your PHP application, and autom A goal of this distribution is to avoid introducing proprietary concepts in addition to those defined by the wider OpenTelemetry community. For any additional features introduced, Elastic aims at contributing them back to the upstream OpenTelemetry project. -## Features +## Features In addition to all the features of OpenTelemetry PHP, with EDOT PHP you have access to the following: diff --git a/docs/reference/edot-sdks/php/migration.md b/docs/reference/edot-sdks/php/migration.md index c75da02b..41bef799 100644 --- a/docs/reference/edot-sdks/php/migration.md +++ b/docs/reference/edot-sdks/php/migration.md @@ -72,7 +72,7 @@ Switch from `php.ini`-based configuration to environment variables. Below is a c | `elastic_apm.secret_token = token123` | `OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token123"` | Sets auth header for OTLP exporter | | `elastic_apm.environment = production` | `OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production` | Adds environment context to exported data | -:::tip +:::{tip} EDOT PHP does not require changes to your code or Composer configuration — instrumentation works automatically after package installation. ::: @@ -164,6 +164,6 @@ You’re now ready to start collecting traces and metrics using OpenTelemetry wi EDOT PHP does not currently support span compression. As a result, traces may be more verbose and produce higher cardinality, especially in loop-heavy code. -:::note +:::{note} For a broader overview of known limitations — including technical constraints related to PHP runtime and extensions — see the [Limitations](./setup/limitations.md) page. ::: \ No newline at end of file diff --git a/docs/reference/edot-sdks/php/setup/index.md b/docs/reference/edot-sdks/php/setup/index.md index 5ca420b6..47566301 100644 --- a/docs/reference/edot-sdks/php/setup/index.md +++ b/docs/reference/edot-sdks/php/setup/index.md @@ -76,7 +76,7 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....==" ### Run EDOT PHP -:::warning +:::{warning} After completing the configuration, you should restart the PHP process. If you are using PHP as an Apache Webserver module or PHP-FPM, you need to perform a **full** process restart to ensure that the extension with the agent is loaded correctly. ::: @@ -88,7 +88,7 @@ To confirm that EDOT PHP has successfully connected to Elastic: 1. You should see the name of the service to which you just added EDOT PHP. It can take several minutes after initializing EDOT PHP for the service to show up in this list. 1. Click on the name in the list to see trace data. -:::note +:::{note} There may be no trace data to visualize unless you have _used_ your application since initializing EDOT PHP. ::: diff --git a/docs/reference/edot-sdks/php/supported-technologies.md b/docs/reference/edot-sdks/php/supported-technologies.md index 5ce04db2..08f6281d 100644 --- a/docs/reference/edot-sdks/php/supported-technologies.md +++ b/docs/reference/edot-sdks/php/supported-technologies.md @@ -17,7 +17,7 @@ products: EDOT PHP sends data via the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support it is strongly recommended that you use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. -:::note +:::{note} Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ *is supported*. ::: @@ -26,7 +26,7 @@ See [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. ## PHP Versions - PHP 8.1 - 8.4 -:::note +:::{note} Unlike the upstream OpenTelemetry PHP agent, EDOT PHP supports extension-level instrumentation starting from PHP 8.1 (not just 8.2). This allows you to capture **detailed traces** from libraries such as **cURL**, **PDO**, and **MySQLi**, even in PHP 8.1 environments. ::: @@ -72,7 +72,7 @@ EDOT PHP supports all popular variations of using PHP in combination with a web - **Asynchronous data sending** Sends telemetry data in the background to avoid impacting application performance, ensuring minimal latency and efficient resource usage. -:::note +:::{note} EDOT PHP supports background data transmission (non-blocking export), but **only when the exporter is set to `http/protobuf` (OTLP over HTTP)** — which is the default configuration. If you change the exporter or the transport protocol (e.g., to gRPC or another format), telemetry data will be sent **synchronously**, potentially impacting request latency. ::: \ No newline at end of file diff --git a/docs/reference/edot-sdks/php/troubleshooting.md b/docs/reference/edot-sdks/php/troubleshooting.md index a8a78ed2..3a371025 100644 --- a/docs/reference/edot-sdks/php/troubleshooting.md +++ b/docs/reference/edot-sdks/php/troubleshooting.md @@ -33,7 +33,7 @@ Additionally, it is recommended to enable logging for OpenTelemetry components, export OTEL_LOG_LEVEL=DEBUG ``` -:::important +:::{note} Please upload your complete debug logs to a service like [GitHub Gist](https://gist.github.com) so that we can analyze the problem. Logs should include everything from when the application starts up until the first request executes. It is important to note that logs may contain sensitive data — be sure to review and sanitize them before sharing. ::: @@ -45,7 +45,7 @@ you can disable the agent while you troubleshoot. You can disable the agent by setting [`elastic_otel.enabled`](./configuration.md#general-configuration) to `false`. -:::important +:::{note} You'll need to restart your application for the changes to apply. ::: @@ -72,7 +72,7 @@ export ELASTIC_OTEL_NATIVE_OTLP_SERIALIZER_ENABLED=false Restart your application and check if spans/logs/metrics start appearing correctly. -:::note +:::{note} When disabled, the agent falls back to a PHP-based serializer, which has lower performance. ::: @@ -111,7 +111,7 @@ If there are multiple PHP processes in your system, we allow you to specify dire - `%t` - In this place, the agent will substitute the UNIX timestamp. -:::warning IMPORTANT +:::{warning} IMPORTANT After setting the path, remember to _fully restart the process_ for which you are collecting diagnostic information. This may vary depending on the context, such as PHP, PHP-FPM, Apache, or PHP-CGI. Diagnostic information will be recorded after the first HTTP request is made or at the beginning of script execution for PHP-CLI. Please also be aware that the information contained in the output file may include sensitive data, such as passwords, security tokens or environment variables from your system. Make sure to review the data and mask sensitive information before sharing the file publicly. diff --git a/docs/reference/quickstart/serverless/k8s.md b/docs/reference/quickstart/serverless/k8s.md index 5f36ad73..e1c7c793 100644 --- a/docs/reference/quickstart/serverless/k8s.md +++ b/docs/reference/quickstart/serverless/k8s.md @@ -106,6 +106,6 @@ Exporting failed. Dropping data. Format your API key as `"Authorization": "ApiKey "` or `"Authorization=ApiKey "` depending on whether you're using a Collector or SDK. -### Error: too many requests +### Error: too many requests The managed endpoint has per-project rate limits in place. If you reach this limit, contact our [support team](https://support.elastic.co). diff --git a/docs/reference/use-cases/kubernetes/customization.md b/docs/reference/use-cases/kubernetes/customization.md index b21db9b5..00b219f3 100644 --- a/docs/reference/use-cases/kubernetes/customization.md +++ b/docs/reference/use-cases/kubernetes/customization.md @@ -30,7 +30,7 @@ The following table lists common parameters that might be relevant for your use For more information on all available parameters and their meaning, refer to: * The provided `values.yaml`, which includes the default settings for the EDOT installation. -* The official OpenTelemetry `kube-stack` Helm chart [values file](https://raw.githubusercontent.com/elastic/elastic-agent/refs/tags/v{{ site.edot_versions.collector }}/deploy/helm/edot-collector/kube-stack/values.yaml), with explanations of all parameters. +* The official OpenTelemetry `kube-stack` Helm chart [values file](https://github.com/elastic/elastic-agent/blob/main/deploy/helm/edot-collector/kube-stack/values.yaml), with explanations of all parameters. ## Cert-manager integrated installation diff --git a/docs/reference/use-cases/kubernetes/prerequisites-compatibility.md b/docs/reference/use-cases/kubernetes/prerequisites-compatibility.md index 41ceaa70..0792a733 100644 --- a/docs/reference/use-cases/kubernetes/prerequisites-compatibility.md +++ b/docs/reference/use-cases/kubernetes/prerequisites-compatibility.md @@ -14,7 +14,7 @@ products: Before setting up observability for Kubernetes, make sure you have the following: -- Elastic Stack (self-managed or [Elastic Cloud](https://www.elastic.co/cloud)) version 8.16.0 or higher, or an [Elasticsearch serverless](https://www.elastic.co/docs/current/serverless/elasticsearch/get-started) project. +- Elastic Stack (self-managed or [Elastic Cloud](https://www.elastic.co/cloud)) version 8.16.0 or higher, or an [Elasticsearch serverless](docs-content://solutions/search/serverless-elasticsearch-get-started.md) project. - A Kubernetes version supported by the OpenTelemetry Operator. Refer to the operator's [compatibility matrix](https://github.com/open-telemetry/opentelemetry-operator/blob/main/docs/compatibility.md#compatibility-matrix) for more details. From 32069b6d6552570edc1ca8d5d27feecbacdb0406 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 13 May 2025 11:12:41 +0200 Subject: [PATCH 02/14] Migration docs for python --- docs/reference/edot-sdks/dotnet/migration.md | 2 +- docs/reference/edot-sdks/java/migration.md | 2 +- docs/reference/edot-sdks/nodejs/migration.md | 4 +- docs/reference/edot-sdks/php/migration.md | 2 +- docs/reference/edot-sdks/python/migration.md | 149 ++++++++----------- 5 files changed, 67 insertions(+), 92 deletions(-) diff --git a/docs/reference/edot-sdks/dotnet/migration.md b/docs/reference/edot-sdks/dotnet/migration.md index 521d6589..168b65ce 100644 --- a/docs/reference/edot-sdks/dotnet/migration.md +++ b/docs/reference/edot-sdks/dotnet/migration.md @@ -12,7 +12,7 @@ products: - id: apm-dotnet-agent --- -# Migrating to EDOT .NET +# Migrate to EDOT .NET from the Elastic APM .NET agent The observability industry is shifting to adopt [OpenTelemetry](https://opentelemetry.io/). At Elastic, we are focused on contributing to help OpenTelemetry succeed, and OpenTelemetry-native support is being introduced across all Elastic diff --git a/docs/reference/edot-sdks/java/migration.md b/docs/reference/edot-sdks/java/migration.md index d6e36d5b..3a4e3b02 100644 --- a/docs/reference/edot-sdks/java/migration.md +++ b/docs/reference/edot-sdks/java/migration.md @@ -12,7 +12,7 @@ products: - id: apm-java-agent --- -# Migrating to EDOT Java from the Elastic Java Agent +# Migrate to EDOT Java from the Elastic APM Java agent This documentation describes how to update applications that are currently using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) to use the Elastic Distribution of OpenTelemetry Java (EDOT Java). diff --git a/docs/reference/edot-sdks/nodejs/migration.md b/docs/reference/edot-sdks/nodejs/migration.md index 7563b24c..14356360 100644 --- a/docs/reference/edot-sdks/nodejs/migration.md +++ b/docs/reference/edot-sdks/nodejs/migration.md @@ -12,7 +12,7 @@ products: - id: apm-node-agent --- -# Migrating to EDOT Node.js from the Elastic Node.js Agent +# Migrating to EDOT Node.js from the Elastic APM Node.js agent This documentation describes how to update applications that are currently using the [Elastic APM Node.js agent](https://www.elastic.co/guide/en/apm/agent/nodejs/current/index.html) (npm package `elastic-apm-node`) to use the Elastic Distribution of OpenTelemetry for Node.js (EDOT Node.js, npm package `@elastic/opentelemetry-node`). @@ -201,5 +201,3 @@ For example: `OTEL_METRIC_EXPORT_INTERVAL=30000`. The Elastic APM Node.js agent [`cloudProvider`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#cloud-provider) option does not corresponds directly to an OpenTelemetry option but you can get similar behaviour by properly setting [`OTEL_NODE_RESOURCE_DETECTORS`](https://opentelemetry.io/docs/zero-code/js/configuration/#sdk-resource-detector-configuration) option. If you set this option make sure you add along with the cloud detector the non-cloud detectors that apply to your service. For a full list of detectors check [OTEL_NODE_RESOURCE_DETECTORS details](./configuration.md#otel_node_resource_detectors-details). Not setting this option is the equivalent of `auto`. For example: `OTEL_NODE_RESOURCE_DETECTORS=os,env,host,serviceinstance,process,aws` will make the agent query for AWS metadata only and use other non-cloud detectors to enrich that metadata. - - diff --git a/docs/reference/edot-sdks/php/migration.md b/docs/reference/edot-sdks/php/migration.md index 41bef799..7d6ec25a 100644 --- a/docs/reference/edot-sdks/php/migration.md +++ b/docs/reference/edot-sdks/php/migration.md @@ -12,7 +12,7 @@ products: - id: apm-php-agent --- -# Migrating to EDOT PHP from the Elastic PHP Agent +# Migrating to EDOT PHP from the Elastic APM PHP agent Follow these steps to migrate from the legacy Elastic APM PHP agent (`elastic-apm-php`) to the Elastic Distribution of OpenTelemetry PHP (`elastic-otel-php`). diff --git a/docs/reference/edot-sdks/python/migration.md b/docs/reference/edot-sdks/python/migration.md index f2a8a31d..f861ff67 100644 --- a/docs/reference/edot-sdks/python/migration.md +++ b/docs/reference/edot-sdks/python/migration.md @@ -12,139 +12,116 @@ products: - id: apm-python-agent --- -# Migrating to EDOT Python from the Elastic APM Python Agent +# Migrate to EDOT Python from the Elastic APM Python agent -This guide will highlight the major differences between the [Elastic APM Python agent](https://www.elastic.co/guide/en/apm/agent/python/current/getting-started.html) and the Elastic Distribution of OpenTelemetry Python (EDOT Python). +Learn the differences between the [Elastic APM Python agent](apm-agent-python://reference/index.md) and the Elastic Distribution of OpenTelemetry Python (EDOT Python). -For step-by-step instructions on setting up EDOT Python refer to [Setup](./setup/index.md). +Follow the steps to migrate your instrumentation and settings. For step-by-step instructions on setting up EDOT Python refer to [Setup](./setup/index.md). -## We are a distribution - -As a distribution of OpenTelemetry, EDOT Python follows certain standards, but there is still some space for innovation. - -## EDOT Python principles - -### Bold on auto-instrumentation - -We have chosen to make auto-instrumentation as simple as possible so you can just focus on your code; we favored an experience that requires minimal changes to your application code. The upstream OpenTelemetry configuration has more options than the distribution requires. Our default configuration is listed [here](https://github.com/elastic/elastic-otel-python?tab=readme-ov-file#configuration). - -### Bring your own instrumentation - -In EDOT Python we decided to not ship all the available instrumentations in order to accommodate environments where installing more packages than requested may be an issue. -We provide a tool to discover available instrumentations automatically that can be added to your build workflow. See the [Setup](./setup/index.md#install-the-available-instrumentation). +## Migration steps -## Performance overhead +Follow these steps to migrate: -Evaluate the [differences in performance overhead](./overhead.md) between EDOT Python and Elastic APM Python agent. +1. Remove any configuration and setup code needed by Elastic APM Python Agent from your application source code. +2. Migrate any usage of Elastic APM Python Agent API to manual instrumentation with OpenTelemetry API in the application source code. +3. Follow the [setup documentation](setup/index.md) on to install and configure EDOT Python. -## Limitations +## Configuration migration -### Central and Dynamic configuration +The following are Elastic APM Python agent settings that you can migrate to EDOT Python. -Currently EDOT Python does not have an equivalent of the [central configuration feature](https://www.elastic.co/guide/en/observability/current/apm-agent-configuration.html) that the Elastic APM Python agent supports. When using EDOT Python, all the configurations are static and should be provided to the application with other configurations, e.g. environment variables. +### `api_key` -### AWS lambda +The Elastic [`api_key`](apm-agent-python://reference/configuration.md#config-api-key) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. -At the moment, we are not building a custom lambda layer for our Python distribution. You can refer to the upstream [Lambda Auto-Instrumentation](https://opentelemetry.io/docs/faas/lambda-auto-instrument/). +For example: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_api_key"`. -### Missing instrumentations +### `enabled` -Not all instrumentations we have in Elastic APM Python Agent have an OpenTelemetry counterpart. But we may port them if they are requested by users. +The Elastic [`enabled`](apm-agent-python://reference/configuration.md#config-enabled) option corresponds to the OpenTelemetry [OTEL_SDK_DISABLED](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) option. -At the time of writing these docs, the following libraries are missing an OpenTelemetry instrumentation: -- aiobotocore -- aiomysql -- aiopg -- aioredis -- Azure storage and Azure queue -- Graphene -- httplib2 -- pylibmc -- pyodbc -- Sanic -- zlib +### `environment` -### Integration with structured logging +The Elastic [`environment`](apm-agent-python://reference/configuration.md#config-environment) option corresponds to setting the `deployment.environment.name` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). -EDOT Python does not have any [structlog integration](https://www.elastic.co/guide/en/apm/agent/python/current/logs.html#structlog) at the moment. +For example: `OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=testing`. -### Span compression +### `global_labels` -EDOT Python does not implement [span compression](https://www.elastic.co/guide/en/observability/current/apm-data-model-spans.html#apm-spans-span-compression). +The Elastic [`global_labels`](apm-agent-python://reference/configuration.md#config-global_labels) option corresponds to adding `key=value` comma separated pairs in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). -### Breakdown metrics +For example: `OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second`. Such labels will result in labels.key=value attributes on the server, e.g. labels.alice=first -EDOT Python is not sending metrics that power the [Breakdown metrics](https://www.elastic.co/guide/en/apm/guide/current/data-model-metrics.html#_breakdown_metrics). +### `metrics_interval` -## Migration steps +The Elastic [`metrics_interval`](apm-agent-python://reference/configuration.md#config-metrics_interval) corresponds to the OpenTelemetry [OTEL_METRIC_EXPORT_INTERVAL](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader) option. -- remove any configuration and setup code needed by Elastic APM Python Agent from your application source code. -- migrate any eventual usage of Elastic APM Python Agent API for manual instrumentation with OpenTelemetry API in the application source code. -- follow [setup documentation](setup/index.md) on how to install and configure EDOT Python +For example: `OTEL_METRIC_EXPORT_INTERVAL=30000`. -## Option reference +### `secret_token` -This list contains Elastic APM Python agent configuration options that can be migrated to EDOT Python configuration because they have an equivalent in OpenTelemetry: +The Elastic [`secret_token`](apm-agent-python://reference/configuration.md#config-secret-token) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. - -* [api_key](#api_key) -* [enabled](#enabled) -* [environment](#environment) -* [global_labels](#global_labels) -* [metrics_interval](#metrics_interval) -* [secret_token](#secret_token) -* [server_url](#server_url) -* [service_name](#service_name) -* [service_version](#service_version) +For example: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_apm_secret_token"`. -### `api_key` +### `server_url` -The Elastic [`api_key`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-api-key) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. +The Elastic [`server_url`](apm-agent-python://reference/configuration.md#config-server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option. -For example:`OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_api_key"`. +### `service_name` -### `enabled` +The Elastic [`service_name`](apm-agent-python://reference/configuration.md#config-service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option. -The Elastic [`enabled`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-enabled) option corresponds to the OpenTelemetry [OTEL_SDK_DISABLED](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) option. +You can also set the service name using [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). -### `environment` +For example: `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. If `OTEL_SERVICE_NAME` is set, it takes precedence over the resource attribute. -The Elastic [`environment`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-environment) option corresponds to setting the `deployment.environment.name` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +### `service_version` -For example: `OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=testing`. +The Elastic [`service_version`](apm-agent-python://reference/configuration.md#config-service-version) option corresponds to setting the `service.version` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). -### `global_labels` +For example: `OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3`. -The Elastic [`global_labels`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-global_labels) option corresponds to adding `key=value` comma separated pairs in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +## Performance overhead -For example: `OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second`. Such labels will result in labels.key=value attributes on the server, e.g. labels.alice=first +Evaluate the [differences in performance overhead](./overhead.md) between EDOT Python and Elastic APM Python agent. -### `metrics_interval` +## Limitations -The Elastic [`metrics_interval`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-metrics_interval) corresponds to the OpenTelemetry [OTEL_METRIC_EXPORT_INTERVAL](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader) option. +The following limitations apply when migrating to EDOT Python. -For example: `OTEL_METRIC_EXPORT_INTERVAL=30000`. +### Central and dynamic configuration -### `secret_token` +EDOT Python lacks an equivalent to the [central configuration feature](docs-content://solutions/observability/apm/configure-apm-agent-central-configuration.md) that the Elastic APM Python agent supports. When using EDOT Python, all of the configurations are static and you should provide them to the application through other means, such as environment variables. -The Elastic [`secret_token`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-secret-token) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. +### AWS Lambda -For example: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_apm_secret_token"`. +A custom lambda layer for the Elastic Distribution of OpenTelemetry Python is not currently available. Refer to the upstream [Lambda Auto-Instrumentation](https://opentelemetry.io/docs/faas/lambda-auto-instrument/). -### `server_url` +### Missing instrumentations -The Elastic [`server_url`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option. +The following libraries are currently missing an OpenTelemetry equivalent: -### `service_name` +- Azure storage and Azure queue +- `aiobotocore` +- `aiomysql` +- `aiopg` +- `aioredis` +- `Graphene` +- `httplib2` +- `pylibmc` +- `pyodbc` +- `Sanic` +- `zlib` -The Elastic [`service_name`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option. +### Integration with structured logging -The service name value can also be set using [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +EDOT Python lacks a [structlog integration](apm-agent-python://reference/logs.md#structlog) at the moment. -For example: `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. If `OTEL_SERVICE_NAME` is set, it takes precedence over the resource attribute. +### Span compression -### `service_version` +EDOT Python does not implement [span compression](docs-content://solutions/observability/apm/spans.md#apm-spans-span-compression). -The Elastic [`service_version`](https://www.elastic.co/guide/en/apm/agent/python/current/configuration.html#config-service-version) option corresponds to setting the `service.version` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +### Breakdown metrics -For example: `OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3`. +EDOT Python is not sending metrics that power the [Breakdown metrics](docs-content://solutions/observability/apm/metrics.md#_breakdown_metrics). \ No newline at end of file From 89d433af317fd8fa43ff5f95cba6c2034b67066f Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 13 May 2025 11:28:27 +0200 Subject: [PATCH 03/14] PHP migration --- docs/reference/edot-sdks/php/migration.md | 158 ++++++++++--------- docs/reference/edot-sdks/python/migration.md | 2 +- 2 files changed, 81 insertions(+), 79 deletions(-) diff --git a/docs/reference/edot-sdks/php/migration.md b/docs/reference/edot-sdks/php/migration.md index 7d6ec25a..cac0195d 100644 --- a/docs/reference/edot-sdks/php/migration.md +++ b/docs/reference/edot-sdks/php/migration.md @@ -12,57 +12,78 @@ products: - id: apm-php-agent --- -# Migrating to EDOT PHP from the Elastic APM PHP agent +# Migrate to EDOT PHP from the Elastic APM PHP agent + +Compared to the Elastic APM PHP agent, the Elastic Distribution of OpenTelemetry PHP presents a number of advantages: + +- Fully automatic instrumentation with zero code changes. No need to modify application code, add Composer packages, or wrap bootstrap files. +- EDOT PHP is built on top of OpenTelemetry SDK and conventions, ensuring compatibility with community tools, vendor-neutral backends, and so on. +- Modular, extensible architecture based on the OpenTelemetry SDK. You can add custom exporters, processors, and samplers. +- You can use EDOT PHP in environments where both tracing and metrics are collected using OpenTelemetry. + +## Migration steps Follow these steps to migrate from the legacy Elastic APM PHP agent (`elastic-apm-php`) to the Elastic Distribution of OpenTelemetry PHP (`elastic-otel-php`). -### 1. Uninstall the Elastic APM PHP agent +::::::{stepper} + +:::::{step} Uninstall the Elastic APM PHP agent Remove the previously installed `elastic-apm-php` package: -**Debian/Ubuntu:** +::::{tab-set} +:::{tab-item} Debian/Ubuntu ```bash sudo dpkg -r elastic-apm-php ``` +::: -**CentOS/Fedora:** - +:::{tab-item} CentOS/Fedora ```bash sudo rpm -e elastic-apm-php ``` +::: -**Alpine Linux:** - +:::{tab-item} Alpine Linux ```bash sudo apk del elastic-apm-php ``` +::: -### 2. Install EDOT PHP +:::: +::::: + +:::::{step} Install EDOT PHP Download the appropriate package for your system from the [GitHub releases page](https://github.com/elastic/elastic-otel-php/releases). -**Debian/Ubuntu:** +::::{tab-set} +:::{tab-item} Debian/Ubuntu ```bash sudo dpkg -i elastic-otel-php__amd64.deb ``` +::: -**CentOS/Fedora:** - +:::{tab-item} CentOS/Fedora ```bash sudo rpm -ivh elastic-otel-php--1.x86_64.rpm ``` +::: -**Alpine Linux:** - +:::{tab-item} Alpine Linux ```bash sudo apk add --allow-untrusted elastic-otel-php-.apk ``` +::: + +:::: +::::: -### 3. Update configuration +:::::{step} Update configuration -Switch from `php.ini`-based configuration to environment variables. Below is a common mapping between old and new settings: +Switch from `php.ini`-based configuration to environment variables. The following is a common mapping between old and new settings: | Elastic APM (php.ini) | EDOT PHP (environment variable) | Description | | -------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | @@ -72,19 +93,50 @@ Switch from `php.ini`-based configuration to environment variables. Below is a c | `elastic_apm.secret_token = token123` | `OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token123"` | Sets auth header for OTLP exporter | | `elastic_apm.environment = production` | `OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production` | Adds environment context to exported data | -:::{tip} +::::{tip} EDOT PHP does not require changes to your code or Composer configuration — instrumentation works automatically after package installation. +:::: +::::: | + +:::::{step} Restart your PHP environment + +Restart the relevant PHP processes for changes to take effect. This might include: + +::::{tab-set} + +:::{tab-item} PHP-FPM +```bash +sudo systemctl restart php8.x-fpm +``` ::: -### Full Configuration Mapping: Elastic APM PHP → EDOT PHP +:::{tab-item} Apache +```bash +sudo systemctl restart apache2 +``` +::: + +:::{tab-item} CLI scripts +```bash +php script.php +``` +::: + +:::: +::::: +:::::: + +## Configuration mapping + +The following are Elastic APM PHP agent settings that you can migrate to EDOT PHP. | Elastic APM PHP Option | EDOT PHP Environment variable equivalent Option | Description | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `api_key` | [`OTEL_EXPORTER_OTLP_HEADERS`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_headers) | Set API key via OTLP headers. Example: `Authorization=Bearer `. | -| `breakdown_metrics` | ❌ | No span compression or breakdown-type metric generation (yet). | -| `capture_errors` | ❌ | No direct equivalent. Handled via standard error handling and inferred spans. | +| `breakdown_metrics` | Not available | No span compression or breakdown-type metric generation (yet). | +| `capture_errors` | Not available | No direct equivalent. Handled via standard error handling and inferred spans. | | `disable_instrumentations` | [`OTEL_PHP_DISABLED_INSTRUMENTATIONS`](https://opentelemetry.io/docs/languages/php/sdk/#configuration) | Comma-separated list of instrumentations to disable. | -| `disable_send` | ❌ | No direct option. Could potentially be simulated with custom exporters or filtering processors. | +| `disable_send` | Not available | No direct option. Could potentially be simulated with custom exporters or filtering processors. | | `enabled` | [`ELASTIC_OTEL_ENABLED`](./configuration.md#general-configuration) | Enables or disables EDOT PHP instrumentation entirely. | | `environment` | [`OTEL_RESOURCE_ATTRIBUTES`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_resource_attributes) | Add deployment metadata (e.g., `deployment.environment=prod`). | | `global_labels` | [`OTEL_RESOURCE_ATTRIBUTES`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_resource_attributes) | Set global key-value pairs for all spans/metrics. | @@ -92,12 +144,12 @@ EDOT PHP does not require changes to your code or Composer configuration — ins | `server_url` | [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint) | Sets OTLP exporter endpoint. Defaults to `http://localhost:4318`. | | `service_name` | [`OTEL_SERVICE_NAME`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_service_name) | Defines service name for traces/metrics. | | `transaction_sample_rate` | [`OTEL_TRACES_SAMPLER_ARG`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler_arg) | Sampling rate for traces (e.g., `0.25`). | -| `transaction_max_spans` | ❌ | No direct support in PHP SDK for limiting spans per transaction. | +| `transaction_max_spans` | Not available | No direct support in PHP SDK for limiting spans per transaction. | | `span_frames_min_duration` | [`ELASTIC_OTEL_INFERRED_SPANS_MIN_DURATION`](./configuration.md#inferred-spans-configuration) | Duration threshold for inferred spans. | -| `sanitize_field_names` | ❌ | Not yet supported in EDOT PHP. | +| `sanitize_field_names` | Not available | Not yet supported in EDOT PHP. | | `verify_server_cert` | [`ELASTIC_OTEL_VERIFY_SERVER_CERT`](./configuration.md#asynchronous-data-sending-configuration) | Enable or disable SSL verification when exporting telemetry. | | `transaction_ignore_urls` | [`OTEL_PHP_EXCLUDED_URLS`](https://opentelemetry.io/docs/languages/php/sdk/#configuration) | A comma-separated list of regex patterns for excluding incoming HTTP URLs from tracing (e.g., `client/.*/info,healthcheck`). | -| `transaction_name_callback` | ❌ | No equivalent for callback-based naming; use grouping or manual `setAttribute()`. | +| `transaction_name_callback` | Not available | No equivalent for callback-based naming; use grouping or manual `setAttribute()`. | | `log_level_syslog` | [`ELASTIC_OTEL_LOG_LEVEL_SYSLOG`](./configuration.md#logging-configuration) | Sets syslog sink verbosity. | | `log_level_file` | [`ELASTIC_OTEL_LOG_LEVEL_FILE`](./configuration.md#logging-configuration) | Controls log level for file-based output. | | `log_level_stderr` | [`ELASTIC_OTEL_LOG_LEVEL_STDERR`](./configuration.md#logging-configuration) | Controls log level for stderr (recommended in containers). | @@ -106,64 +158,14 @@ EDOT PHP does not require changes to your code or Composer configuration — ins | `transaction_url_groups` | [`ELASTIC_OTEL_TRANSACTION_URL_GROUPS`](./configuration.md#transaction-span-configuration) | Group similar URL paths (e.g., `/user/*`). | | `inferred_spans_enabled` | [`ELASTIC_OTEL_INFERRED_SPANS_ENABLED`](./configuration.md#inferred-spans-configuration) | Enables inferred spans (preview). | | `inferred_spans_sampling_interval` | [`ELASTIC_OTEL_INFERRED_SPANS_SAMPLING_INTERVAL`](./configuration.md#inferred-spans-configuration) | Sampling frequency for stack traces during inferred spans. | -| `inferred_spans_min_duration` | [`ELASTIC_OTEL_INFERRED_SPANS_MIN_DURATION`](./configuration.md#inferred-spans-configuration) | Minimum duration of inferred span (used to limit noise). | - -### 4. Restart your PHP environment - -Restart the relevant PHP processes for changes to take effect. This could include: - -- PHP-FPM: - ```bash - sudo systemctl restart php8.x-fpm - ``` - -- Apache: - ```bash - sudo systemctl restart apache2 - ``` - -- CLI scripts: - ```bash - php script.php - ``` - -You’re now ready to start collecting traces and metrics using OpenTelemetry with Elastic! - -## Advantages of EDOT PHP over the Classic Elastic APM Agent - -### Fully automatic instrumentation with zero code changes -- No need to modify application code, add Composer packages, or wrap bootstrap files. -- Works out-of-the-box after system package installation. -- No need to register SDK, bootstrap, or start a tracer manually — everything is handled by the agent at the extension level. - -### OpenTelemetry standard compliance -- EDOT PHP is built on top of **OpenTelemetry SDK and conventions**, ensuring compatibility with: - - community tools, - - vendor-neutral backends, - - standard propagation formats (`traceparent`, `baggage`), - - open observability pipelines (e.g., EDOT Collector or OpenTelemetry Collector). - -### Modular, extensible architecture -- Based on the OpenTelemetry SDK — you can add custom exporters, processors, and samplers. -- Easy to extend or adapt to advanced use cases (e.g., exporting to multiple backends). - -### Better future-proofing and community alignment -- EDOT PHP benefits from: - - upstream OpenTelemetry improvements, - - Elastic-specific early bugfixes and features, - - community-driven instrumentation libraries and patterns. - -### Unified telemetry collection (traces + metrics) -- EDOT PHP can be used in environments where **both tracing and metrics** are collected using OpenTelemetry. -- The classic APM agent focuses solely on APM/tracing. -## Limitations Compared to the Elastic APM Agent +| `inferred_spans_min_duration` | [`ELASTIC_OTEL_INFERRED_SPANS_MIN_DURATION`](./configuration.md#inferred-spans-configuration) | Minimum duration of inferred span (used to limit noise). -- Lack of Span Compression +## Limitations - The classic Elastic APM agent includes span compression, which merges multiple similar spans (e.g., repeated SQL queries or HTTP calls) into a single composite span to reduce trace noise and overhead. +The following limitations apply to EDOT PHP: - EDOT PHP does not currently support span compression. As a result, traces may be more verbose and produce higher cardinality, especially in loop-heavy code. +- Lack of span compression: The classic Elastic APM agent includes span compression, which merges multiple similar spans. EDOT PHP doesn't currently support span compression. As a result, traces may be more verbose and produce higher cardinality, especially in loop-heavy code. :::{note} -For a broader overview of known limitations — including technical constraints related to PHP runtime and extensions — see the [Limitations](./setup/limitations.md) page. +For a broader overview of known limitations — including technical constraints related to PHP runtime and extensions, refer to [Limitations](./setup/limitations.md). ::: \ No newline at end of file diff --git a/docs/reference/edot-sdks/python/migration.md b/docs/reference/edot-sdks/python/migration.md index f861ff67..80fdd0bb 100644 --- a/docs/reference/edot-sdks/python/migration.md +++ b/docs/reference/edot-sdks/python/migration.md @@ -26,7 +26,7 @@ Follow these steps to migrate: 2. Migrate any usage of Elastic APM Python Agent API to manual instrumentation with OpenTelemetry API in the application source code. 3. Follow the [setup documentation](setup/index.md) on to install and configure EDOT Python. -## Configuration migration +## Configuration mapping The following are Elastic APM Python agent settings that you can migrate to EDOT Python. From 14e5aadb12943fe8d7f47cd68efce7a5b4f035f0 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 13 May 2025 12:02:42 +0200 Subject: [PATCH 04/14] Migration java --- docs/reference/edot-sdks/java/migration.md | 171 +++++++++---------- docs/reference/edot-sdks/nodejs/migration.md | 163 +++++++++--------- 2 files changed, 167 insertions(+), 167 deletions(-) diff --git a/docs/reference/edot-sdks/java/migration.md b/docs/reference/edot-sdks/java/migration.md index 3a4e3b02..4d2c7771 100644 --- a/docs/reference/edot-sdks/java/migration.md +++ b/docs/reference/edot-sdks/java/migration.md @@ -13,121 +13,72 @@ products: --- # Migrate to EDOT Java from the Elastic APM Java agent - -This documentation describes how to update applications that are currently using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) to use the Elastic Distribution of OpenTelemetry Java (EDOT Java). -## Advantages of using EDOT Java agent +Compared to the Elastic APM Java agent, the Elastic Distribution of OpenTelemetry Java presents a number of advantages: -### OpenTelemetry-native Data +- Fully automatic instrumentation with zero code changes. No need to modify application code. +- Capture, send, transform and store data in an OpenTelemetry native way. This includes for example the ability to use all features of the OpenTelemetry SDK for manual tracing, data following semantic conventions or ability to use intermediate collectors and processors. +- OpenTelemetry Java Instrumentation provides a [broad coverage of libraries, frameworks and applications](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md). +- EDOT Java is built on top of OpenTelemetry SDK and conventions, ensuring compatibility with community tools, vendor-neutral backends, and so on. -Allows to capture, send, transform and store data in an OpenTelemetry native way. This includes for example the ability to use all features of the OpenTelemetry SDK for manual tracing, data following semantic conventions or ability to use intermediate collectors and processors. - -### Broad Coverage of Instrumentation - -OpenTelemetry Java Instrumentation provides a [broad coverage of libraries, frameworks and applications](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md). - -- [Libraries and frameworks](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks) -- [Application servers](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#application-servers) - -### Compatible Drop-in Replacement - -The upstream OpenTelemetry Java Agent is a vendor-neutral implementation. -EDOT Java is a distribution of it and is thus a - fully compatible drop-in replacement of the upstream OpenTelemetry Java Agent. - -Hence, exclusive features of EDOT aside, there is no vendor lock-in through proprietary instrumentation or agent. - -## Limitations - -### Supported Java Versions - -EDOT Java agent and OpenTelemetry Java instrumentation are only compatible with Java 8 and later. - -### Missing Instrumentations - -Support for LDAP client instrumentation is not available in EDOT Java, yet. +## Migration steps -### Central and Dynamic configuration +Follow these steps to migrate from the legacy Elastic APM Java agent to the Elastic Distribution of OpenTelemetry Java. -Currently EDOT Java does not have an equivalent of the [central configuration feature](https://www.elastic.co/guide/en/observability/current/apm-agent-configuration.html) that the Elastic APM Java agent supports. When using EDOT Java, all the configurations are static and should be provided to the application with other configurations, e.g. environment variables. +::::::{stepper} -### Span compression +::::{step} (Optional) Migrate manual instrumentation API -EDOT Java does not implement [span compression](https://www.elastic.co/guide/en/observability/current/apm-data-model-spans.html#apm-spans-span-compression). +Migrate usages of the [Elastic APM Agent API](apm-agent-java://reference/public-api.md) to OpenTelemetry API: -### Breakdown metrics +- For [Annotation API](apm-agent-java://reference/public-api.md#api-annotation), refer to [OpenTelemetry Annotations](https://opentelemetry.io/docs/zero-code/java/agent/annotations/). +- For [Transaction API](apm-agent-java://reference/public-api.md#api-transaction), refer to [OpenTelemetry API](https://opentelemetry.io/docs/zero-code/java/agent/api/). -EDOT Java is not sending metrics that power the [Breakdown metrics](https://www.elastic.co/guide/en/apm/guide/current/data-model-metrics.html#_breakdown_metrics). +:::{note} +Migration of application code using these APIs and annotations is not strictly required when deploying the EDOT agent. If not migrated, spans, transactions, and metrics that were previously created with those custom API calls and annotations will no longer be generated. OpenTelemetry instrumentation coverage might replace the need for some or all of these custom code changes. +::: +:::: -### No remote attach +::::{step} Replace configuration options +Refer to the [Configuration mapping](#configuration-mapping). Refer to [Configuration](./configuration.md) for ways to provide configuration settings. +:::: -There is currently no EDOT Java equivalent for starting the agent with the [remote attach](https://www.elastic.co/guide/en/apm/agent/java/current/setup-attach-cli.html) capability. The `-javaagent:` option is the preferred startup mechanism. There is a migration path for starting the agent with [self attach](https://www.elastic.co/guide/en/apm/agent/java/current/setup-attach-api.html), which is to use [runtime attachment](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/runtime-attach/README.md). +::::{step} Replace the agent binary -### Micrometer disabled by default +Remove the `-javaagent:` argument that contains the Elastic APM Java agent from the JVM arguments. Then add the `-javaagent:` argument to the JVM arguments to use EDOT Java, and restart the application or follow [Kubernetes instructions](./setup/k8s.md) if applicable. Refer to [Setup](./setup/index.md) +:::: -By default, micrometer instrumentation is disabled and won't capture metrics, enabling requires to set `otel.instrumentation.micrometer.enabled=true`. +:::::: -## Migration steps +## Configuration mapping -1. **Review all pros/cons of this migration guide** including the [differences in performance overhead](./overhead.md). -1. **(Optional) Migrate manual instrumentation API:** Usages of the [Elastic APM Agent API](https://www.elastic.co/guide/en/apm/agent/java/current/public-api.html) require migration to OpenTelemetry API: - - for [Annotation API](https://www.elastic.co/guide/en/apm/agent/java/current/public-api.html#api-annotation) see [OpenTelemetry Annotations](https://opentelemetry.io/docs/zero-code/java/agent/annotations/). - - for [Transaction API](https://www.elastic.co/guide/en/apm/agent/java/current/public-api.html#api-transaction) see [OpenTelemetry API](https://opentelemetry.io/docs/zero-code/java/agent/api/). - - :::{note} - Migration of application code using these APIs and annotations is _not strictly required_ when deploying the EDOT agent. If not migrated, the spans, transactions and metrics that were previously explicitly created with those custom API calls and annotations, will no longer be generated. The broader OpenTelemetry instrumentation coverage may replace the need for some or all of these custom code changes. - ::: -1. **Replace configuration options** using the [Reference](#option-reference) below, see [Configuration](./configuration.md) for ways to provide those. -1. **Replace Agent binary** - - Remove the `-javaagent:` argument containing [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) from the JVM arguments - - Add `-javaagent:` argument to the JVM arguments to use EDOT Java and restart the application or follow [Kubernetes instructions](./setup/k8s.md) if applicable - -## Option reference - -This list contains APM Java agent configuration options that can be migrated to EDOT Java agent configuration because -they have an equivalent in OpenTelemetry: - -* [server_url](#server_url) -* [server_urls](#server_urls) -* [secret_token](#secret_token) -* [api_key](#api_key) -* [service_name](#service_name) -* [enabled](#enabled) -* [service_version](#service_version) -* [environment](#environment) -* [global_labels](#global_labels) -* [trace_methods](#trace_methods) -* [capture_jmx_metrics](#capture_jmx_metrics) -* [capture_headers](#capture_headers) -* [span_stack_trace_min_duration](#span_stack_trace_min_duration) -* [disable_instrumentations](#disable_instrumentations) -* [enable_instrumentations](#enable_instrumentations) +The following are Elastic APM Java agent settings that you can migrate to EDOT Java. ### `server_url` -The Elastic [`server_url`](https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option. +The Elastic [`server_url`](apm-agent-java://reference/config-reporter.md#config-server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option. ### `server_urls` -The Elastic [`server_urls`](https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-server-urls) option has no equivalent OpenTelemetry option - you can only specify one endpoint. +The Elastic [`server_urls`](apm-agent-java://reference/config-reporter.md#config-server-urls) option has no equivalent OpenTelemetry option. You can only specify one endpoint. Use [OTEL_EXPORTER_OTLP_ENDPOINT](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) instead. ### `secret_token` -The Elastic [`secret_token`](https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-secret-token) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. +The Elastic [`secret_token`](apm-agent-java://reference/config-reporter.md#config-secret-token) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. For example: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token"`. ### `api_key` -The Elastic [`api_key`](https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-api-key) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. +The Elastic [`api_key`](apm-agent-java://reference/config-reporter.md#config-api-key) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. For example:`OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_api_key"`. ### `service_name` -The Elastic [`service_name`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option. +The Elastic [`service_name`](apm-agent-java://reference/config-core.md#config-service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option. The service name value can also be set using [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). @@ -135,23 +86,23 @@ For example: `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. If `OTEL_SERVICE ### `enabled` -The Elastic [`enabled`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-enabled) option corresponds to the OpenTelemetry [OTEL_JAVAAGENT_ENABLED](https://opentelemetry.io/docs/zero-code/java/agent/disable/) option. +The Elastic [`enabled`](apm-agent-java://reference/config-core.md#config-enabled) option corresponds to the OpenTelemetry [OTEL_JAVAAGENT_ENABLED](https://opentelemetry.io/docs/zero-code/java/agent/disable/) option. ### `service_version` -The Elastic [`service_version`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-service-version) option corresponds to setting the `service.version` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +The Elastic [`service_version`](apm-agent-java://reference/config-core.md#config-service-version) option corresponds to setting the `service.version` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3`. ### `environment` -The Elastic [`environment`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-environment) option corresponds to setting the `deployment.environment` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +The Elastic [`environment`](apm-agent-java://reference/config-core.md#config-environment) option corresponds to setting the `deployment.environment` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=deployment.environment=testing`. ### `global_labels` -The Elastic [`global_labels`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-global-labels) option corresponds to adding `key=value` comma separated pairs in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +The Elastic [`global_labels`](apm-agent-java://reference/config-core.md#config-global-labels) option corresponds to adding `key=value` comma separated pairs in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second`. Such labels will result in labels.key=value attributes on the server, e.g. labels.alice=first @@ -165,31 +116,71 @@ The Elastic [`capture_jmx_metrics`](https://www.elastic.co/guide/en/apm/agent/ja [OpenTelemetry JMX Insight](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/javaagent/) feature which is included in EDOT Java. The JMX Insight feature provides the following benefits: -- ability to define custom metrics using YAML -- capturing metrics with pre-defined metrics by using `OTEL_JMX_TARGET_SYSTEM` configuration option. + +- Ability to define custom metrics using YAML. +- Capturing metrics with pre-defined metrics by using `OTEL_JMX_TARGET_SYSTEM` configuration option. ### `capture_headers` -The Elastic `capture_headers` option can be replaced with the following options: +Replace the Elastic `capture_headers` option with the following options: + - `otel.instrumentation.http.server.capture-request-headers` for HTTP server request - `otel.instrumentation.http.server.capture-response-headers` for HTTP server response - `otel.instrumentation.http.client.capture-request-headers` for HTTP client request - `otel.instrumentation.http.client.capture-response-headers` for HTTP client response - `otel.instrumentation.messaging.experimental.capture-headers` for messaging -Note that the `capture_headers` option is dyamically adjustable, while the `otel.*` options are statically set by startup and cannot be subsequently adjusted +The `capture_headers` option is dynamically adjustable, while the `otel.*` options are statically set by startup and cannot be subsequently adjusted. ### `span_stack_trace_min_duration` -The Elastic `span_stack_trace_min_duration` option can be replaced with [`OTEL_JAVA_EXPERIMENTAL_SPAN_STACKTRACE_MIN_DURATION`](./features.md#span-stacktrace). +Replace the Elastic `span_stack_trace_min_duration` option with [`OTEL_JAVA_EXPERIMENTAL_SPAN_STACKTRACE_MIN_DURATION`](./features.md#span-stacktrace). ### `disable_instrumentations` -The `disable_instrumentations` option allows to selectively disable instrumentation (opt-out) can be replaced with `OTEL_INSTRUMENTATION__ENABLED` where `` is the instrumentation name. +Replace the `disable_instrumentations` option, which allows to selectively disable instrumentation (opt-out), with `OTEL_INSTRUMENTATION__ENABLED` where `` is the instrumentation name. + See [OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/agent/disable/) for reference and values. ### `enable_instrumentations` The `enable_instrumentations` option allows to disable all instrumentation enabled by default and selectively enable instrumentation (opt-in) can be replaced with: -- `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED` = `false` to disable instrumentations enabled by default + +- `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED` = `false` to disable instrumentations enabled by default. - `OTEL_INSTRUMENTATION__ENABLED` = `true` where `` is the name of the instrumentation to enable. See [OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/agent/disable/) for reference and values. + +## Limitations + +The following limitations apply to EDOT Java. + +### Supported Java versions + +EDOT Java agent and OpenTelemetry Java instrumentation are only compatible with Java 8 and later. + +### Missing instrumentations + +Support for LDAP client instrumentation is not currently available in EDOT Java. + +### Central and dynamic configuration + +Currently EDOT Java does not have an equivalent of the [central configuration feature](docs-content://solutions/observability/apm/apm-agent-central-configuration.md) that the Elastic APM Java agent supports. + +When using EDOT Java, all the configurations are static and should be provided to the application with other configurations, such as environment variables. + +### Span compression + +EDOT Java does not implement [span compression](docs-content://solutions/observability/apm/spans.md#apm-spans-span-compression). + +### Breakdown metrics + +EDOT Java is not sending metrics that power the [Breakdown metrics](docs-content://solutions/observability/apm/metrics.md#_breakdown_metrics). + +### No remote attach + +There is currently no EDOT Java equivalent for starting the agent with the [remote attach](apm-agent-java://reference/setup-attach-cli.md) capability. The `-javaagent:` option is the preferred startup mechanism. + +There is a migration path for starting the agent with [self attach](apm-agent-java://reference/setup-attach-api.md), which is to use [runtime attachment](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/main/runtime-attach/README.md). + +### Micrometer turned off by default + +By default, Micrometer instrumentation is inactive and doesn't capture metrics. To turn it on, use the `otel.instrumentation.micrometer.enabled=true` setting. \ No newline at end of file diff --git a/docs/reference/edot-sdks/nodejs/migration.md b/docs/reference/edot-sdks/nodejs/migration.md index 14356360..6dc7d563 100644 --- a/docs/reference/edot-sdks/nodejs/migration.md +++ b/docs/reference/edot-sdks/nodejs/migration.md @@ -12,141 +12,127 @@ products: - id: apm-node-agent --- -# Migrating to EDOT Node.js from the Elastic APM Node.js agent +# Migrate to EDOT Node.js from the Elastic APM Node.js agent -This documentation describes how to update applications that are currently using the [Elastic APM Node.js agent](https://www.elastic.co/guide/en/apm/agent/nodejs/current/index.html) (npm package `elastic-apm-node`) to use the Elastic Distribution of OpenTelemetry for Node.js (EDOT Node.js, npm package `@elastic/opentelemetry-node`). +Compared to the Elastic APM Node.js agent, the Elastic Distribution of OpenTelemetry Node.js presents a number of advantages: -## Advantages of using EDOT Node.js agent +- Fully automatic instrumentation with zero code changes. No need to modify application code. +- EDOT Node.js is built on top of OpenTelemetry SDK and conventions, ensuring compatibility with community tools, vendor-neutral backends, and so on. +- Modular, extensible architecture based on the OpenTelemetry SDK. You can add custom exporters, processors, and samplers. +- You can use EDOT Node.js in environments where both tracing and metrics are collected using OpenTelemetry. -### Compatible Drop-in Replacement -The upstream `@opentelemetry/auto-instrumentations-node` package is a vendor-neutral implementation. -EDOT Node.js is a distribution of it and is thus a fully compatible drop-in replacement of the `@opentelemetry/auto-instrumentations-node` package. +## Migration steps -### OpenTelemetry-native Data +Follow these steps to migrate from the legacy Elastic APM PHP agent (`elastic-apm-node`) to the Elastic Distribution of OpenTelemetry PHP (`@elastic/opentelemetry-node`). -Allows to capture, send, transform and store data in an OpenTelemetry native way. This includes for example the ability to use all features of the OpenTelemetry SDK for manual tracing, data following semantic conventions or ability to use intermediate collectors and processors. +::::::{stepper} -## Limitations +::::{step} Replace the Node.js package -### Supported Node.js versions +Remove the Elastic APM Node.js Agent package and install EDOT Node.js: -EDOT Node.js and OpenTelemetry upstream SDK support Node.js versions in the range `^18.19.0 || >=20.6.0`. -Elastic APM Node.js works with Node.js versions `>=14.17.0`, though with limited support for Node.js 14 and 16 given that those major versions of Node.js are out of long-term support. +```sh +npm uninstall elastic-apm-node +npm install --save @elastic/opentelemetry-node +``` -### Missing Instrumentations +:::: -EDOT Node.js does not yet support instrumentation for AWS Lambda and Azure Functions. However, there are upstream and third-party options based on OpenTelemetry: +::::{step} Remove APM Node.js start method -- For AWS Lambda use [OpenTelemetry Lambda layers](https://github.com/open-telemetry/opentelemetry-lambda). -- For Azure Functions you can [configure OpenTelemetry](https://learn.microsoft.com/en-us/azure/azure-functions/opentelemetry-howto?tabs=app-insights&pivots=programming-language-javascript). +For services starting the APM Node.js Agent by using `require()` with the [require and start](apm-agent-nodejs://reference/starting-agent.md#start-option-require-and-start) or [require start module](apm-agent-nodejs://reference/starting-agent.md#start-option-require-start-module) methods, the `require('elastic-apm-node')`, remove the code. -### Central configuration +For services starting with the [`--require` Node.js CLI option](apm-agent-nodejs://reference/starting-agent.md#start-option-node-require-opt), remove the option. If the `--require` option is defined in `NODE_OPTIONS` environment variable, remove it there. -Currently EDOT Node.js does not yet have an equivalent of the [central configuration feature](https://www.elastic.co/guide/en/observability/current/apm-agent-configuration.html) that the Elastic APM Node.js agent supports. When using EDOT Node.js, all the configurations are static and must be provided to the application as environment variables. +:::: -### Span compression +::::{step} (Optional) Migrate manual instrumentation API +If you're using the [Elastic APM Node.js Agent API](apm-agent-nodejs://reference/api.md) to create manual transactions and spans you should refactor the code to use `@opentelemetry/api` methods. OpenTelemetry documentation has several examples of how to [create spans](https://opentelemetry.io/docs/languages/js/instrumentation/#create-spans) manually. +:::: -EDOT Node.js does not implement [span compression](https://www.elastic.co/guide/en/observability/current/apm-data-model-spans.html#apm-spans-span-compression). +::::{step} Replace configuration options +Refer to the [Configuration mapping](#configuration-mapping). Refer to [Configuration](./configuration.md) for details on EDOT Node.js configuration. +:::: -## Migration steps +::::{step} Add EDOT Node.js start method -1. **Replace Node.js package** - - Remove the Elastic APM Node.js Agent package: `npm uninstall elastic-apm-node` - - Install EDOT Node.js: `npm install --save @elastic/opentelemetry-node` -2. **Remove APM Node.js start method** - - For services starting the APM Node.js Agent by `require()`ing in the code with the [require and start](https://www.elastic.co/guide/en/apm/agent/nodejs/current/starting-the-agent.html#start-option-require-and-start) or [require start module](https://www.elastic.co/guide/en/apm/agent/nodejs/current/starting-the-agent.html#start-option-require-start-module) methods, the `require('elastic-apm-node')` code should be removed. - - For services starting with the [`--require` Node.js CLI option](https://www.elastic.co/guide/en/apm/agent/nodejs/current/starting-the-agent.html#start-option-node-require-opt) the option should be removed. If the `--require` option is defined in `NODE_OPTIONS` environment variable it should be removed from there. -3. **(Optional) Migrate manual instrumentation API:** If you're using the [Elastic APM Node.js Agent API](https://www.elastic.co/guide/en/apm/agent/nodejs/current/api.html) to create manual transactions and spans you should refactor the code to use `@opentelemetry/api` methods. OpenTelemetry documentaion has several examples of how to [create spans](https://opentelemetry.io/docs/languages/js/instrumentation/#create-spans) manually. -4. **Replace configuration options** using the [Configuration migration reference](#configuration-migration-reference) below. See [Configuration](./configuration.md) for details on EDOT Node.js configuration. -5. **Add EDOT Node.js start method:** - Use the [Node.js `--import` option](https://nodejs.org/api/cli.html#--importmodule) to start EDOT Node.js with your service: - - Set it on the command-line -- `node --import @elastic/opentelemetry-node service.js` -- or - - in the [`NODE_OPTIONS` environment variable](https://nodejs.org/api/cli.html#node_optionsoptions): `NODE_OPTIONS="--import @elastic/opentelemetry-node" node service.js` - -## Configuration migration reference - -This list contains Elastic APM Node.js agent configuration options that can be migrated to EDOT Node.js SDK configuration because they have an equivalent in OpenTelemetry: - -* [serverUrl](#serverurl) -* [secretToken](#secrettoken) -* [apiKey](#apikey) -* [serviceName](#servicename) -* [active](#active) -* [serviceVersion](#serviceversion) -* [environment](#environment) -* [globalLabels](#globallabels) -* [transactionSampleRate](#transactionsamplerate) -* [logLevel](#loglevel) -* [maxQueueSize](#maxqueuesize) -* [serverTimeout](#servertimeout) -* [apmClientHeaders](#apmclientheaders) -* [disableInstrumentations](#disableinstrumentations) -* [metricsInterval](#metricsinterval) -* [cloudProvider](#cloudprovider) +Use the [Node.js `--import` option](https://nodejs.org/api/cli.html#--importmodule) to start EDOT Node.js with your service. + +Set it on the command-line using `node --import @elastic/opentelemetry-node service.js` or in the [`NODE_OPTIONS` environment variable](https://nodejs.org/api/cli.html#node_optionsoptions): `NODE_OPTIONS="--import @elastic/opentelemetry-node" node service.js`. +:::: + +:::::: + +## Configuration mapping + +This list contains Elastic APM Node.js agent configuration options that can be migrated to EDOT Node.js SDK configuration because they have an equivalent in OpenTelemetry. ### `serverUrl` -The Elastic APM Node.js agent [`serverUrl`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option. +The Elastic APM Node.js agent [`serverUrl`](apm-agent-nodejs://reference/configuration.md#server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option. -- If using Elastic Cloud Serverless, then set `OTEL_EXPORTER_OTLP_ENDPOINT` to the managed OTLP endpoint URL for your Serverless project, e.g. `OTEL_EXPORTER_OTLP_ENDPOINT=https://my-prj-a1b2c3.ingest.eu-west-1.aws.elastic.cloud`. See the [Quickstart for Elastic Cloud Serverless](../../quickstart/serverless/index.md). +- If using Elastic Cloud Serverless, set `OTEL_EXPORTER_OTLP_ENDPOINT` to the managed OTLP endpoint URL for your Serverless project. For example, `OTEL_EXPORTER_OTLP_ENDPOINT=https://my-prj-a1b2c3.ingest.eu-west-1.aws.elastic.cloud`. Refer to the [Quickstart for Elastic Cloud Serverless](../../quickstart/serverless/index.md). -- If using Elastic Cloud Hosted or Self-managed, then set `OTEL_EXPORTER_OTLP_ENDPOINT` to the endpoint URL of your EDOT Collector. See the [Quickstart for Elastic Cloud Hosted](../../quickstart/ech/hosts_vms.md) or the [Quickstart for Self-managed](../../quickstart/self-managed/hosts_vms.md). +- If using Elastic Cloud Hosted or Self-managed, set `OTEL_EXPORTER_OTLP_ENDPOINT` to the endpoint URL of your EDOT Collector. Refer to the [Quickstart for Elastic Cloud Hosted](../../quickstart/ech/hosts_vms.md) or the [Quickstart for Self-managed](../../quickstart/self-managed/hosts_vms.md). ### `secretToken` -The Elastic APM Node.js agent [`secretToken`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#secret-token) option corresponds to setting the `Authorization` header in the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. +The Elastic APM Node.js agent [`secretToken`](apm-agent-nodejs://reference/configuration.md#secret-token) option corresponds to setting the `Authorization` header in the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. For example: `OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer an_apm_secret_token"`. :::{note} -Secret token usage is discouraged and Elastic recomends the usage of API keys for authentication. +Secret token usage is discouraged. Use API keys for authentication. ::: ### `apiKey` -The Elastic APM Node.js agent [`apiKey`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#api-key) option corresponds to setting the `Authorization` header in the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. +The Elastic APM Node.js agent [`apiKey`](apm-agent-nodejs://reference/configuration.md#api-key) option corresponds to setting the `Authorization` header in the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. For example:`OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_api_key"`. ### `serviceName` -The Elastic APM Node.js agent [`serviceName`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option. +The Elastic APM Node.js agent [`serviceName`](apm-agent-nodejs://reference/configuration.md#service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option. -The service name value can also be set using [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. A value in `OTEL_SERVICE_NAME` takes precedence over a `service.name` value in `OTEL_RESOURCE_ATTRIBUTES`. +You can also set the service name using [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. A value in `OTEL_SERVICE_NAME` takes precedence over a `service.name` value in `OTEL_RESOURCE_ATTRIBUTES`. ### `active` -The Elastic APM Node.js agent [`active`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#active) option corresponds to the OpenTelemetry [OTEL_SDK_DISABLED](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) option but it has the opposite meaning. Set the `OTEL_SDK_DISABLED` to `true` if you want to deactivate the agent. +The Elastic APM Node.js agent [`active`](apm-agent-nodejs://reference/configuration.md#active) option corresponds to the OpenTelemetry [OTEL_SDK_DISABLED](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) option but it has the opposite meaning. -For example: `OTEL_SDK_DISABLED=true`. +Set the `OTEL_SDK_DISABLED` to `true` if you want to deactivate the agent. For example: `OTEL_SDK_DISABLED=true`. ### `serviceVersion` -The Elastic APM Node.js agent [`serviceVersion`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#service-version) option corresponds to setting the `service.version` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +The Elastic APM Node.js agent [`serviceVersion`](apm-agent-nodejs://reference/configuration.md#service-version) option corresponds to setting the `service.version` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3`. ### `environment` -The Elastic APM Node.js agent [`environment`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#environment) option corresponds to setting the `deployment.environment` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +The Elastic APM Node.js agent [`environment`](apm-agent-nodejs://reference/configuration.md#environment) option corresponds to setting the `deployment.environment` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=deployment.environment=testing`. ### `globalLabels` -The Elastic APM Node.js agent [`globalLabels`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#global-labels) option corresponds to adding `key=value` comma separated pairs in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). +The Elastic APM Node.js agent [`globalLabels`](apm-agent-nodejs://reference/configuration.md#global-labels) option corresponds to adding `key=value` comma separated pairs in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). -For example: `OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second`. Such labels will result in labels.key=value attributes on the server, e.g. labels.alice=first +For example: `OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second`. Such labels will result in labels.key=value attributes on the server. For example, `labels.alice=first`. ### `transactionSampleRate` -The Elastic APM Node.js agent [`transactionSampleRate`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#transaction-sample-rate) corresponds to the OpenTelemetry `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG` options. For example, for the equivalent of `transactionSampleRate: '0.25'` use `OTEL_TRACES_SAMPLER=parentbased_traceidratio OTEL_TRACES_SAMPLER_ARG=0.25`. +The Elastic APM Node.js agent [`transactionSampleRate`](apm-agent-nodejs://reference/configuration.md#transaction-sample-rate) corresponds to the OpenTelemetry `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG` options. + +For example, for the equivalent of `transactionSampleRate: '0.25'` use `OTEL_TRACES_SAMPLER=parentbased_traceidratio OTEL_TRACES_SAMPLER_ARG=0.25`. ### `logLevel` -The Elastic APM Node.js agent [`logLevel`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#log-level) option corresponds to the OpenTelemetry [`OTEL_LOG_LEVEL`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) option. The possible values change a bit but they represent similar levels. The following -table shows the equivalent values of log levels between `elastic-apm-node` and EDOT Node.js. +The Elastic APM Node.js agent [`logLevel`](apm-agent-nodejs://reference/configuration.md#log-level) option corresponds to the OpenTelemetry [`OTEL_LOG_LEVEL`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) option. + +The following table shows the equivalent values of log levels between `elastic-apm-node` and EDOT Node.js. | ELASTIC_APM_LOG_LEVEL | OTEL_LOG_LEVEL | | --------------------- | -------------- | @@ -160,7 +146,7 @@ table shows the equivalent values of log levels between `elastic-apm-node` and E ### `maxQueueSize` -The Elastic APM Node.js agent [`maxQueueSize`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#max-queue-size) option corresponds to a couple of OpenTelemetry options: +The Elastic APM Node.js agent [`maxQueueSize`](apm-agent-nodejs://reference/configuration.md#max-queue-size) option corresponds to a couple of OpenTelemetry options: - [`OTEL_BSP_MAX_QUEUE_SIZE`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-span-processor) option to set the queue size for spans. - [`OTEL_BLRP_MAX_QUEUE_SIZE`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-span-processor) option to set the queue size for logs. @@ -170,7 +156,7 @@ For example: `OTEL_BSP_MAX_QUEUE_SIZE=2048 OTEL_BLRP_MAX_QUEUE_SIZE=4096`. ### `serverTimeout` -The Elastic APM Node.js agent [`serverTimeout`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#server-timeout) option corresponds to a OpenTelemetry options per signal: +The Elastic APM Node.js agent [`serverTimeout`](apm-agent-nodejs://reference/configuration.md#server-timeout) option corresponds to a OpenTelemetry options per signal: - [`OTEL_BLRP_EXPORT_TIMEOUT`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-logrecord-processor) option for logs. - [`OTEL_BSP_EXPORT_TIMEOUT`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-span-processor) option for spans. @@ -180,24 +166,47 @@ For example: `OTEL_BSP_EXPORT_TIMEOUT=50000 OTEL_BLRP_EXPORT_TIMEOUT=50000 OTEL_ ### `apmClientHeaders` -The Elastic APM Node.js agent [`apmClientHeaders`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#apm-client-headers) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_HEADERS`](https://opentelemetry.io/docs/specs/otel/protocol/exporter/#specifying-headers-via-environment-variables) option. +The Elastic APM Node.js agent [`apmClientHeaders`](apm-agent-nodejs://reference/configuration.md#apm-client-headers) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_HEADERS`](https://opentelemetry.io/docs/specs/otel/protocol/exporter/#specifying-headers-via-environment-variables) option. For example: `OTEL_EXPORTER_OTLP_HEADERS=foo=bar,baz=quux`. ### `disableInstrumentations` -The Elastic APM Node.js agent [`disableInstrumentations`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#apm-client-headers) option corresponds to the EDOT Node.js [`OTEL_NODE_DISABLED_INSTRUMENTATIONS`](./configuration.md#otel_node_disabledenabled_instrumentations-details) option. +The Elastic APM Node.js agent [`disableInstrumentations`](apm-agent-nodejs://reference/configuration.md#apm-client-headers) option corresponds to the EDOT Node.js [`OTEL_NODE_DISABLED_INSTRUMENTATIONS`](./configuration.md#otel_node_disabledenabled_instrumentations-details) option. For example: `OTEL_NODE_DISABLED_INSTRUMENTATIONS=express,mysql`. ### `metricsInterval` -The Elastic APM Node.js agent [`metricsInterval`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#metrics-interval) option corresponds to the OpenTelemetry [`OTEL_METRIC_EXPORT_INTERVAL`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader) option. +The Elastic APM Node.js agent [`metricsInterval`](apm-agent-nodejs://reference/configuration.md#metrics-interval) option corresponds to the OpenTelemetry [`OTEL_METRIC_EXPORT_INTERVAL`](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader) option. For example: `OTEL_METRIC_EXPORT_INTERVAL=30000`. ### `cloudProvider` -The Elastic APM Node.js agent [`cloudProvider`](https://www.elastic.co/guide/en/apm/agent/nodejs/current/configuration.html#cloud-provider) option does not corresponds directly to an OpenTelemetry option but you can get similar behaviour by properly setting [`OTEL_NODE_RESOURCE_DETECTORS`](https://opentelemetry.io/docs/zero-code/js/configuration/#sdk-resource-detector-configuration) option. If you set this option make sure you add along with the cloud detector the non-cloud detectors that apply to your service. For a full list of detectors check [OTEL_NODE_RESOURCE_DETECTORS details](./configuration.md#otel_node_resource_detectors-details). Not setting this option is the equivalent of `auto`. +The Elastic APM Node.js agent [`cloudProvider`](apm-agent-nodejs://reference/configuration.md#cloud-provider) option does not corresponds directly to an OpenTelemetry option but you can get similar behavior by properly setting [`OTEL_NODE_RESOURCE_DETECTORS`](https://opentelemetry.io/docs/zero-code/js/configuration/#sdk-resource-detector-configuration) option. If you set this option make sure you add along with the cloud detector the non-cloud detectors that apply to your service. For a full list of detectors check [OTEL_NODE_RESOURCE_DETECTORS details](./configuration.md#otel_node_resource_detectors-details). Not setting this option is the equivalent of `auto`. For example: `OTEL_NODE_RESOURCE_DETECTORS=os,env,host,serviceinstance,process,aws` will make the agent query for AWS metadata only and use other non-cloud detectors to enrich that metadata. + +## Limitations + +The following limitations apply to EDOT Node.js. + +### Supported Node.js versions + +EDOT Node.js and OpenTelemetry upstream SDK support Node.js versions in the range `^18.19.0 || >=20.6.0`. Elastic APM Node.js works with Node.js versions `>=14.17.0`, though with limited support for Node.js 14 and 16 given that those major versions of Node.js are out of long-term support. + +### Missing instrumentations + +EDOT Node.js doesn't currently support instrumentation for AWS Lambda and Azure Functions. However, there are upstream and third-party options based on OpenTelemetry: + +- For AWS Lambda use [OpenTelemetry Lambda layers](https://github.com/open-telemetry/opentelemetry-lambda). +- For Azure Functions you can [configure OpenTelemetry](https://learn.microsoft.com/en-us/azure/azure-functions/opentelemetry-howto?tabs=app-insights&pivots=programming-language-javascript). + +### Central configuration + +Currently EDOT Node.js does not yet have an equivalent of the [central configuration feature](docs-content://solutions/observability/apm/apm-agent-central-configuration.md) that the Elastic APM Node.js agent supports. When using EDOT Node.js, all the configurations are static and must be provided to the application as environment variables. + +### Span compression + +EDOT Node.js does not implement [span compression](docs-content://solutions/observability/apm/spans.md#apm-spans-span-compression). \ No newline at end of file From 35839041e29b9dc864f9894b1341af3a5f5ef323 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 13 May 2025 12:26:51 +0200 Subject: [PATCH 05/14] Dotnet migration --- docs/reference/edot-sdks/dotnet/migration.md | 200 ++++++------------- 1 file changed, 65 insertions(+), 135 deletions(-) diff --git a/docs/reference/edot-sdks/dotnet/migration.md b/docs/reference/edot-sdks/dotnet/migration.md index 168b65ce..d756ffb2 100644 --- a/docs/reference/edot-sdks/dotnet/migration.md +++ b/docs/reference/edot-sdks/dotnet/migration.md @@ -14,50 +14,26 @@ products: # Migrate to EDOT .NET from the Elastic APM .NET agent -The observability industry is shifting to adopt [OpenTelemetry](https://opentelemetry.io/). At Elastic, we are focused on -contributing to help OpenTelemetry succeed, and OpenTelemetry-native support is being introduced across all Elastic -Observability tooling. OpenTelemetry offers several primary advantages for the industry: +Compared to the Elastic APM .NET agent, the Elastic Distribution of OpenTelemetry .NET presents a number of advantages: - No vendor lock-in through standardized concepts, supporting the use of multiple backend vendors or switching between them. - A single set of application APIs are required to instrument applications. - A wider pool of knowledge, experience and support is available across the OpenTelemetry community. - Efficient data collection and advanced data processing opportunities. -At Elastic, we believe the responsible choice is to concentrate on enabling and encouraging customers to favor vendor-neutral instrumentation -in their code and reap the benefits of OpenTelemetry. Engineering teams should be preparing to adopt OpenTelemetry and planning -to migrate existing application instrumentation from vendor-specific agents to the standardized OpenTelemetry SDKs. +While you can use the upstream [OpenTelemetry SDK for .NET](https://github.com/open-telemetry/opentelemetry-dotnet) to directly export data to an Elastic Observability backend, some capabilities of the Elastic tooling might not be able to function as intended. Use the Elastic Distribution of OpenTelemetry (EDOT) language SDK and the [Elastic Distribution of OpenTelemetry collector](../../edot-collector/index.md) for the best experience. -While the upstream [OpenTelemetry SDK for .NET](https://github.com/open-telemetry/opentelemetry-dotnet) can be used to -directly export data to an Elastic Observability backend (both in Elastic Cloud and on-prem), some capabilities of the -Elastic tooling may not be able to function as intended. For that reason, we provide Elastic distributions that -provide a thin layer over the OpenTelemetry tools to provide our customers with the best compatibility, supportability and features. -We recommend using the Elastic Distribution of OpenTelemetry (EDOT) language SDK and the -[Elastic Distribution of OpenTelemetry collector](../../edot-collector/index.md) for the best experience. +## Migrating from Elastic .NET Agent [migrating-to-edot-net-from-elastic-net-agent] -This page guides migrating to EDOT .NET from either the existing -[Elastic APM Agent for .NET](https://www.elastic.co/guide/en/apm/agent/dotnet/current/index.html) or from the upstream -OpenTelemetry SDK. +Follow these steps to migrate from the legacy Elastic APM .NET agent to the Elastic Distribution of OpenTelemetry .NET. -- [Migrating to EDOT .NET from Elastic .NET Agent](#migrating-to-edot-net-from-elastic-net-agent) -- [Migrating to EDOT .NET from the upstream OpenTelemetry .NET SDK](#migrating-to-edot-net-from-the-upstream-opentelemetry-net-sdk) +### Manual instrumentation -## Migrating to EDOT .NET from Elastic .NET Agent [migrating-to-edot-net-from-elastic-net-agent] +The Elastic APM Agent supports OTel-native trace instrumentation through its [OpenTelemetry Bridge](https://www.elastic.co/guide/en/apm/agent/dotnet/current/opentelemetry-bridge.html) feature, which is active by default. -### Migrating manual application instrumentation +The bridge subscribes to instrumentation created using the [`Activity`](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity) API in .NET. An `Activity` represents a unit of work and aligns with the OpenTelemetry "span" concept. The API name is used for historical backward compatibility. The `Activity` API is the recommended approach to introduce tracing when instrumenting applications. -The Elastic APM Agent supports OTel-native trace instrumentation through its -[OpenTelemetry Bridge](https://www.elastic.co/guide/en/apm/agent/dotnet/current/opentelemetry-bridge.html) feature which is -enabled by default. - -The bridge subscribes to instrumentation created using the [`Activity`](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity) -API in .NET. An `Activity` represents a unit of work and aligns with the OpenTelemetry "span" concept. The API name is used for historical -backward compatibility. The `Activity` API is the recommended approach to introduce tracing when instrumenting applications. - -For applications which are instrumented using the [public API](https://www.elastic.co/guide/en/apm/agent/dotnet/current/public-api.html) -A recommended first step of the existing APM Agent is to consider migrating instrumentation over to the `Activity` API. - -For example, in an ASP.NET Core Razor pages application, we may have manually created a child span below -the parent transaction for the ASP.NET Core request: +For applications which are instrumented using the [public API](https://www.elastic.co/guide/en/apm/agent/dotnet/current/public-api.html), a recommended first step of the existing APM Agent is to consider migrating instrumentation over to the `Activity` API. For example, in an ASP.NET Core Razor pages application, you might have manually created a child span after the parent transaction for the ASP.NET Core request: ```csharp using Elastic.Apm.Api; @@ -82,13 +58,9 @@ public class IndexModel : PageModel } ``` -The preceding code captures (starts and ends) a span within the current transaction. The span is named -"Doing stuff". The second argument specifies the type of work this span represents, "internal" in this -example. Within the async lambda, the work is performed, and a custom label is set. +The preceding code captures, or starts and ends, a span within the current transaction. The span is named `Doing stuff`. The second argument specifies the type of work this span represents, `internal` in this example. Within the async lambda, the work is performed, and a custom label is set. -To convert this to the `Activity` API, first define an `ActivitySource` used to create -`Activity` instances (spans). Typically, you have a few (usually just one) of these for application-specific -instrumentation. Define a static instance somewhere within your application. +To convert this to the `Activity` API, first define an `ActivitySource` used to create `Activity` instances (spans). Typically, you have a few, usually just one, of these for application-specific instrumentation. Define a static instance somewhere within your application. ```csharp public static class Instrumentation @@ -97,8 +69,7 @@ public static class Instrumentation } ``` -The `IndexModel` class can now be updated to prefer the `Activity` API. Spans created through this API -will be automatically observed and sent from the APM Agent by the OpenTelemetry bridge. +You can now update the `IndexModel` class to prefer the `Activity` API. Spans created through this API are automatically observed and sent from the APM Agent by the OpenTelemetry bridge. ```csharp using Microsoft.AspNetCore.Mvc.RazorPages; @@ -120,35 +91,18 @@ public class IndexModel : PageModel } ``` -This code is equivalent to the previous code snippet, but it is now vendor-neutral, preferring the -built-in .NET `Activity` API from the `System.Diagnostics` namespace. +This code is equivalent to the previous code snippet, but is now vendor-neutral, preferring the built-in .NET `Activity` API from the `System.Diagnostics` namespace. -The `Activity` class implements `IDisposable`, allowing us to reduce the nesting of code. `StartActivity` -is called on the `ActivitySource`, which creates and starts an `Activity`. Starting an `Activity` results -in a new span, which may be a child of a parent, if an existing `Activity` is already being tracked. This -is handled automatically by the .NET API. +The `Activity` class implements `IDisposable`, allowing us to reduce the nesting of code. `StartActivity` is called on the `ActivitySource`, which creates and starts an `Activity`. Starting an `Activity` results in a new span, which may be a child of a parent, if an existing `Activity` is already being tracked. This is handled automatically by the .NET API. The overload in the previous example accepts a name for the `Activity`. You can optionally pass an `ActivityKind`, although this defaults to `ActivityKind.Internal`. -The overload we have used accepts a name for the `Activity`, in this example, "Doing stuff". We can -optionally pass an `ActivityKind`, although this defaults to `ActivityKind.Internal`, so we omit that here. +The preceding code uses the `SetTag` method to "activity" variable may be assigned `null`. To reduce instrumentation overhead, `StartActivity` may return `null` if no observers of the `ActivitySource` exist. While the API uses the notion of "tags"; these are functionally equivalent to the OpenTelemetry concept of "attributes. Attributes are used to attach arbitrary information to a span in order to enrich it and provide context when analysing the telemetry data. -The preceding code uses the `SetTag` method to "activity" variable may be assigned `null`. To reduce instrumentation -overhead, `StartActivity` may return `null` if no observers of the `ActivitySource` exist. While the -API uses the notion of "tags"; these are functionally equivalent to the OpenTelemetry concept of "attributes. -Attributes are used to attach arbitrary information to a span in order to enrich it and provide context when -analysing the telemetry data. +### Agent registration -This serves as a brief primer for instrumenting code using the .NET built-in tracing API and the `Activity` -class. Visit the Microsoft documentation for more examples of -[adding distributed tracing instrumentation](https://learn.microsoft.com/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs). +After migrating any manual instrumentation from the Elastic APM Agent public API to the Microsoft `Activity` API, the final step is to switch the observation and export of telemetry signals from the APM Agent to EDOT .NET. -### Migrating agent registration - -After migrating any manual instrumentation from the Elastic APM Agent public API to the Microsoft `Activity` -API, the final step is to switch the observation and export of telemetry signals from the APM Agent to EDOT .NET. - -The precise steps will vary by project template but involve replacing ing the registration of the APM agent. In -all cases, you will need to add the `Elastic.Opentelemetry` [NuGet package](https://www.nuget.org/packages/Elastic.OpenTelemetry) -to your project. +The steps vary by project template. In all cases, you need to add the `Elastic.Opentelemetry` [NuGet package](https://www.nuget.org/packages/Elastic.OpenTelemetry) +to your project: ```xml @@ -158,8 +112,7 @@ to your project. Replace the `` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry). ::: -You may also need to install additional instrumentation libraries to observe signals from specific components, such as -ASP.NET Core. +You might also need to install additional instrumentation libraries to observe signals from specific components, such as ASP.NET Core. ```xml @@ -169,15 +122,14 @@ ASP.NET Core. Replace the `` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore). ::: -In an ASP.NET Core application, the APM Agent is likely registered using the `AddAllElasticApm` extension method -defined on the `IServiceCollection`. +In an ASP.NET Core application, the APM Agent is likely registered using the `AddAllElasticApm` extension method defined on the `IServiceCollection`. ```csharp var builder = WebApplication.CreateBuilder(args); builder.Services.AddAllElasticApm(); ``` -To switch to using EDOT .NET, the preceding code should be replaced. +To switch to using EDOT .NET, replace the preceding code: ```csharp using OpenTelemetry; @@ -188,15 +140,9 @@ builder.AddElasticOpenTelemetry(b => b .WithTracing(t => t.AddSource("MyAppInstrumentation"))); ``` -Here, we prefer the `AddElasticOpenTelemetry` extension method for the `IHostApplicationBuilder`. -By default, EDOT .NET is configured to observe the most common instrumentation and export data via OTLP. -See [opinionated defaults](./setup/edot-defaults.md) for more information. - -The preceding code snippet adds one additional source to be observed, which matches the name -we gave to the `ActivitySource` defined earlier. +The previous snippet adds one additional source to be observed, which matches the name you gave to the `ActivitySource` defined earlier. It also uses the `AddElasticOpenTelemetry` extension method for the `IHostApplicationBuilder`. By default, EDOT .NET is configured to observe the most common instrumentation and export data through OTLP. Refer to [Opinionated defaults](./setup/edot-defaults.md) for more information. -Configuration of the APM Agent is likely to have been achieved using environment variables or by providing settings -using the `appsettings.json` file, typical for ASP.NET Core applications. +Configuration of the APM Agent is likely to have been achieved using environment variables or by providing settings using the `appsettings.json` file, typical for ASP.NET Core applications: ```json { @@ -209,66 +155,62 @@ using the `appsettings.json` file, typical for ASP.NET Core applications. } ``` -The above configuration is no longer required and can be replaced with OpenTelemetry SDK settings. At a -minimum, we need to provide the endpoint for the export of data and the authorization header used to -authenticate. +The previous configuration is no longer required and can be replaced with OpenTelemetry SDK settings. At a minimum, provide the endpoint for the export of data and the authorization header used to authenticate. -The OpenTelemetry SDK is generally configured using environment variables. For this application, we should -set the following to be functionally equivalent during the migration of this sample application. +The OpenTelemetry SDK is generally configured using environment variables. For this application, set the following to be functionally equivalent during the migration of this sample application: - `OTEL_SERVICE_NAME` = "MyApplication" - `OTEL_EXPORTER_OTLP_ENDPOINT` = "https://myapmserver:443" - `OTEL_EXPORTER_OTLP_HEADERS` = "Authorization=Api an_apm_api_key" -The required values for the endpoint and headers can be obtained from your Elastic Observability instance. - -Once migrated, the Elastic APM Agent NuGet package can be removed from your application. +The required values for the endpoint and headers can be obtained from your Elastic Observability instance. After you've migrated, you can remove the Elastic APM Agent NuGet from your application. For more details on registering and configuring EDOT. NET, see the [quickstart](./setup/index.md) documentation. -### Limitations - -Elastic APM Agent includes several features that are not currently supported when using EDOT .NET. Each of -these are being assessed and may be included in contributions to OpenTelemetry or as value-add features of -EDOT .NET in future releases. - -- Stacktrace capture -- Central configuration -- Dynamic configuration -- Span compression - ### Zero-code auto instrumentation -When using the Elastic APM Agent profiler auto instrumentation functionality, the `elastic_apm_profiler_.zip` -will have been downloaded and extracted. The following environment variables will be configured for the -process, service, or IIS application pool. +When using the Elastic APM Agent profiler auto-instrumentation functionality, the `elastic_apm_profiler_.zip` must be downloaded and extracted. The following environment variables are configured for the process, service, or IIS application pool. | Runtime | Environment variable | Description | | -------------- | ----------------------------------- | ----------------------------------------------- | | .NET Framework | COR_ENABLE_PROFILING | Instructs the runtime to enable profiling. | | .NET Framework | COR_PROFILER | Instructs the runtime which profiler to use. | -| .NET Framework | COR_PROFILER_PATH | The location of the profiler | +| .NET Framework | COR_PROFILER_PATH | The location of the profiler. | | .NET | CORECLR_ENABLE_PROFILING | Instructs the runtime to enable profiling. | | .NET | CORECLR_PROFILER | Instructs the runtime which profiler to use. | -| .NET | CORECLR_PROFILER_PATH | The location of the profiler DLL | -| All | ELASTIC_APM_PROFILER_HOME | The directory of the extracted profiler | -| All | ELASTIC_APM_PROFILER_INTEGRATIONS | The location of the ingegrations.yml file | -| All | ELASTIC_APM_SERVER_URL | The URL of the APM Server | -| All | ELASTIC_APM_SECRET_TOKEN | The secret used to authenticate with APM server | +| .NET | CORECLR_PROFILER_PATH | The location of the profiler DLL. | +| All | ELASTIC_APM_PROFILER_HOME | The directory of the extracted profiler. | +| All | ELASTIC_APM_PROFILER_INTEGRATIONS | The location of the ingegrations.yml file. | +| All | ELASTIC_APM_SERVER_URL | The URL of the APM Server. | +| All | ELASTIC_APM_SECRET_TOKEN | The secret used to authenticate with APM server.| -To switch to the EDOT .NET zero-code auto instrumentation, the `COR_*` and `CORECLR_*` environment variables must -be updated to point to the Elastic redistribution of the OpenTelemetry autoinstrumentation profiler. +To switch to the EDOT .NET zero-code auto instrumentation, update the `COR_*` and `CORECLR_*` environment variables to point to the Elastic redistribution of the OpenTelemetry auto-instrumentation profiler. -Please follow the steps in [Using EDOT .NET zero-code instrumentation](./setup/zero-code.md) to configure the profiler. +Follow the steps in [Using EDOT .NET zero-code instrumentation](./setup/zero-code.md) to configure the profiler. -## Migrating to EDOT .NET from the upstream OpenTelemetry .NET SDK [migrating-to-edot-net-from-the-upstream-opentelemetry-net-sdk] +### Limitations + +Elastic APM Agent includes several features that are not currently supported when using EDOT .NET. Each of these are being assessed and may be included in contributions to OpenTelemetry or as value-add features of EDOT .NET in future releases. + +#### Stacktrace capture + +The [stacktrace capture](apm-agent-dotnet://reference/config-stacktrace.md) feature from Elastic APM .NET agent is not currently available in EDOT .NET. + +#### Central and dynamic configuration + +Currently EDOT .NET does not have an equivalent of the [central configuration feature](docs-content://solutions/observability/apm/apm-agent-central-configuration.md) that the Elastic APM .NET agent supports. -Our design goal for EDOT .NET has been to introduce no new concepts and require minimal code changes to migrate -from the upstream OpenTelemetry SDK for .NET to EDOT .NET as easily as possible. Our [opinionated defaults](./setup/edot-defaults.md) -strive to simplify the amount of code required to get started with OpenTelemetry in .NET applications. +When using EDOT .NET, all the configurations are static and should be provided to the application with other configurations, such as environment variables. -In an application which already uses the upstream OpenTelemetry SDK, the following code is an example of how -this would be registered and enabled in an ASP.NET Core application. +#### Span compression + +EDOT .NET does not implement [span compression](docs-content://solutions/observability/apm/spans.md#apm-spans-span-compression). + +## Migrate from the upstream .NET SDK [migrating-to-edot-net-from-the-upstream-opentelemetry-net-sdk] + +EDOT .NET require minimal code changes to migrate from the upstream OpenTelemetry SDK for .NET. The distribution [opinionated defaults](./setup/edot-defaults.md) simplify the amount of code required to get started with OpenTelemetry in .NET applications. + +In an application which already uses the upstream OpenTelemetry SDK, the following code is an example of how this would be registered and enabled in an ASP.NET Core application. ```csharp using OpenTelemetry; @@ -291,16 +233,13 @@ builder.Services.AddOpenTelemetry() .UseOtlpExporter(); ``` -In the preceding code, `AddOpenTelemetry` extension method for the `IServiceCollection` is used -to enable the core components. This method returns an `OpenTelemetryBuilder`, which must be further -configured to enable tracing, metrics and logging, as well as export via OTLP. +In the previous code, `AddOpenTelemetry` extension method for the `IServiceCollection` activates the core components. This method returns an `OpenTelemetryBuilder`, which must be further configured to enable tracing, metrics and logging, as well as export through OTLP. :::{note} -Each contrib instrumentation library must be registered manually when using the SDK. +Register each contrib instrumentation library manually when using the SDK. ::: -To get started with the Elastic Distribution of OpenTelemetry .NET, add the -`Elastic.OpenTelemetry` [NuGet package](https://www.nuget.org/packages/Elastic.OpenTelemetry) +To get started with the Elastic Distribution of OpenTelemetry .NET, add the `Elastic.OpenTelemetry` [NuGet package](https://www.nuget.org/packages/Elastic.OpenTelemetry) reference to your project file: ```xml @@ -311,12 +250,9 @@ reference to your project file: Replace the `` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry). ::: -EDOT .NET includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the -OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry -SDK as a dependency if you want to opt into newer SDK versions. +EDOT .NET includes a transitive dependency on the OpenTelemetry SDK, so you do not need to add the OpenTelemetry SDK package to your project directly. However, you can explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. -Due to the EDOT .NET defaults, less code is required to achieve the same instrumentation behaviour that -the previous code snippet configured for the upstream OpenTelemetry SDK. +Due to the EDOT .NET defaults, less code is required to achieve the same instrumentation behavior that the previous code snippet configured for the upstream OpenTelemetry SDK. For example: ```csharp using OpenTelemetry; @@ -327,20 +263,14 @@ builder.AddElasticOpenTelemetry(b => b .WithTracing(t => t.AddSource("AppInstrumentation"))); ``` -EDOT .NET enables all signals by default, so the registration code is less verbose. EDOT .NET also -performs instrumentation assembly scanning to automatically add instrumentation from any contrib libraries -that it finds deployed with the application. All that is required is the installation of the relevant -instrumentation NuGet packages. +EDOT .NET activates all signals by default, so the registration code is less verbose. EDOT .NET also performs instrumentation assembly scanning to automatically add instrumentation from any contrib libraries that it finds deployed with the application. All that is required is the installation of the relevant instrumentation NuGet packages. :::{warning} Instrumentation assembly scanning is not supported for applications using native [AOT](https://learn.microsoft.com/dotnet/core/deploying/native-aot) compilation. ::: -### Zero-code auto instrumentation +### Zero-code instrumentation -EDOT .NET ships with a lightly modified redistribution of the OpenTelemetry SDK installation script. -To instrument a .NET application automatically, download and run the installer script for your operating system -from the latest [release](https://github.com/elastic/elastic-otel-dotnet/releases). +EDOT .NET ships with a lightly modified redistribution of the OpenTelemetry SDK installation script. To instrument a .NET application automatically, download and run the installer script for your operating system from the latest [release](https://github.com/elastic/elastic-otel-dotnet/releases). -See the upstream OpenTelemetry SDK documentation for [.NET zero-code instrumentation](https://opentelemetry.io/docs/zero-code/net) -for more examples of using the installation script. \ No newline at end of file +Refer to the upstream OpenTelemetry SDK documentation for [.NET zero-code instrumentation](https://opentelemetry.io/docs/zero-code/net) for more examples of using the installation script. \ No newline at end of file From ee9cd1dae783475146e2dcb5054e6f116d0d9e0a Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 13 May 2025 12:52:47 +0200 Subject: [PATCH 06/14] Supported techs --- .../dotnet/supported-technologies.md | 58 ++++------- .../reference/edot-sdks/java/configuration.md | 11 +++ .../edot-sdks/java/supported-technologies.md | 52 ++++------ .../nodejs/supported-technologies.md | 74 +++++++-------- .../edot-sdks/php/supported-technologies.md | 95 +++++++++++-------- .../edot-sdks/python/configuration.md | 8 ++ .../python/supported-technologies.md | 50 ++++------ 7 files changed, 166 insertions(+), 182 deletions(-) diff --git a/docs/reference/edot-sdks/dotnet/supported-technologies.md b/docs/reference/edot-sdks/dotnet/supported-technologies.md index f80adda4..41221303 100644 --- a/docs/reference/edot-sdks/dotnet/supported-technologies.md +++ b/docs/reference/edot-sdks/dotnet/supported-technologies.md @@ -9,20 +9,19 @@ products: - id: observability --- -# Technologies Supported by EDOT .NET SDK +# Technologies supported by EDOT .NET SDK -EDOT .NET is a distribution of OpenTelemetry .NET SDK, it thus inherits all the supported technologies -from the [upstream SDK](https://github.com/open-telemetry/opentelemetry-dotnet). +EDOT .NET is a distribution of OpenTelemetry .NET SDK. It inherits all the [supported](../../compatibility/nomenclature.md) technologies from the [upstream SDK](https://github.com/open-telemetry/opentelemetry-dotnet). -## EDOT Collector / Elastic Stack versions +## EDOT Collector and Elastic Stack versions -EDOT .NET sends data via the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support it is strongly recommended that you use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. +EDOT .NET sends data through the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support use either the [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. :::{note} -Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ *is supported*. +Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ is supported. ::: -See [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. +Refer to [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. ## .NET Frameworks @@ -31,14 +30,14 @@ This includes the currently supported Microsoft .NET frameworks: | Framework | End of support | |:---------------------- |:------------------- | | .NET Framework 4.6.2 | 12th Jan 2027 | -| .NET Framework 4.7 | _Not announced_ | -| .NET Framework 4.7.1 | _Not announced_ | -| .NET Framework 4.7.2 | _Not announced_ | -| .NET Framework 4.8 | _Not announced_ | -| .NET Framework 4.8.1 | _Not announced_ | +| .NET Framework 4.7 | Not announced | +| .NET Framework 4.7.1 | Not announced | +| .NET Framework 4.7.2 | Not announced | +| .NET Framework 4.8 | Not announced | +| .NET Framework 4.8.1 | Not announced | | .NET 8 | 10th November 2026 | | .NET 9 | 12th May 2026 | -| .NET 10 (preview)¹ | _Not announced_ | +| .NET 10 (preview)¹ | Not announced | 1. Official support begins once this is released (generally available) in November 2025 @@ -47,27 +46,15 @@ and [.NET Support Policy](https://dotnet.microsoft.com/platform/support/policy). ## Instrumentations -Instrumentation for .NET can occur in three main ways: +Instrumentation for .NET can occur in three ways: -1. Built-in OpenTelemetry native instrumentation (the end goal for OpenTelemetry), -where libraries are instrumented using the .NET APIs, requiring no bridging libraries to -be observed. Many Microsoft recent libraries implement OpenTelemetry native instrumentation, and many third parties -are working on such improvements. When native OTel instrumentation -exists, it may be observed directly by the OpenTelemetry SDK (and, by extension, EDOT .NET) by calling -`AddSource` to register the `ActivitySource` used by the instrumented code. -1. [Contrib instrumentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) packages. -These packages "bridge" existing telemetry from libraries to emit or enrich OpenTelemetry spans and metrics. -Some packages have no dependencies and are included with EDOT .NET [by default](./setup/edot-defaults.md). -Others, which bring in transitive dependencies, can be added to applications and registered with the -OpenTelemetry SDK. EDOT .NET provides an instrumentation assembly scanning feature to register any contrib instrumentation without code changes. -1. Additional instrumentation is available for some components and libraries when using the -profiler-based [zero code installation](./setup/zero-code.md), for which EDOT .NET does not add any additional -instrumentation. The current list supported upstream can be found in the -[.NET zero-code documentation](https://opentelemetry.io/docs/zero-code/dotnet/instrumentations/). +1. Built-in OpenTelemetry native instrumentation, where libraries are instrumented using the .NET APIs, requiring no bridging libraries to be observed. Many Microsoft recent libraries implement OpenTelemetry native instrumentation, and many third parties are working on such improvements. When native OTel instrumentation exists, it may be observed directly by the OpenTelemetry SDK (and, by extension, EDOT .NET) by calling `AddSource` to register the `ActivitySource` used by the instrumented code. -See also the EDOT .NET [opinionated defaults](./setup/edot-defaults.md) for behaviour that might differ from the -OpenTelemetry NET SDK defaults. +2. [Contrib instrumentation](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) packages. These packages bridge existing telemetry from libraries to emit or enrich OpenTelemetry spans and metrics. Some packages have no dependencies and are included with EDOT .NET [by default](./setup/edot-defaults.md). Others, which bring in transitive dependencies, can be added to applications and registered with the OpenTelemetry SDK. EDOT .NET provides an instrumentation assembly scanning feature to register any contrib instrumentation without code changes. +3. Additional instrumentation is available for some components and libraries when using the profiler-based [zero code installation](./setup/zero-code.md), for which EDOT .NET does not add any additional instrumentation. Find the current list supported upstream in the [.NET zero-code documentation](https://opentelemetry.io/docs/zero-code/dotnet/instrumentations/). + +See also the EDOT .NET [opinionated defaults](./setup/edot-defaults.md) for behavior that might differ from the OpenTelemetry NET SDK defaults. :::{warning} Instrumentation assembly scanning is not supported for applications using native [AOT](https://learn.microsoft.com/dotnet/core/deploying/native-aot) compilation. @@ -76,11 +63,8 @@ Instrumentation assembly scanning is not supported for applications using native ## .NET runtime support EDOT .NET support all [officially supported](https://dotnet.microsoft.com/en-us/platform/support/policy) versions of [.NET](https://dotnet.microsoft.com/download/dotnet) and -[.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework)¹ (an older Windows-based .NET implementation), except `.NET Framework 3.5`. - -1. *Due to assembly binding issues introduced by Microsoft, we recommend at least .NET Framework 4.7.2 for best compatibility.* +[.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework) (an older Windows-based .NET implementation), except `.NET Framework 3.5`. Due to assembly binding issues introduced by Microsoft, use at least .NET Framework 4.7.2 for best compatibility. -## Exporting Data to Elastic +## Exporting data to Elastic -Data can be exported in the OpenTelemetry-native [OTLP (OpenTelemetry protocol)](https://opentelemetry.io/docs/specs/otlp) format via gRPC (recommended) -and HTTP to self-managed, Elastic Cloud Hosted or Elastic Cloud Serverless observability backends. \ No newline at end of file +You can export data in the OpenTelemetry-native [OTLP (OpenTelemetry protocol)](https://opentelemetry.io/docs/specs/otlp) format through gRPC and HTTP to self-managed, Elastic Cloud Hosted, or Elastic Cloud Serverless observability. \ No newline at end of file diff --git a/docs/reference/edot-sdks/java/configuration.md b/docs/reference/edot-sdks/java/configuration.md index d7fad382..58c210c6 100644 --- a/docs/reference/edot-sdks/java/configuration.md +++ b/docs/reference/edot-sdks/java/configuration.md @@ -69,6 +69,17 @@ This table only contains minimal configuration, see each respective feature for | `ELASTIC_OTEL_UNIVERSAL_PROFILING_INTEGRATION_ENABLED` | `auto` | [Elastic Universal profiling integration](./features.md#elastic-universal-profiling-integration) | | `OTEL_INSTRUMENTATION_OPENAI_CLIENT_ENABLED` | `true` | [OpenAI client instrumentation](./supported-technologies.md#openai-client-instrumentation) | +## OpenAI Client settings + +The following settings are available: + +| Option | default | description | +|-------------------------------------------------------|---------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `OTEL_INSTRUMENTATION_OPENAI_CLIENT_ENABLED` | `true` | enables or disable OpenAI instrumentation | +| `ELASTIC_OTEL_JAVA_INSTRUMENTATION_GENAI_EMIT_EVENTS` | value of `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | If set to `true`, the agent will generate log events for OpenAI requests and responses. Potentially sensitive content will only be included if `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` is `true` | +| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false` | If set to `true`, enables the capturing of OpenAI request and response content in the log events outputted by the agent. ↪ | + + ## Configuration methods Configuration can be provided through multiple [configuration methods](#configuration-methods): diff --git a/docs/reference/edot-sdks/java/supported-technologies.md b/docs/reference/edot-sdks/java/supported-technologies.md index 46be57e3..153016eb 100644 --- a/docs/reference/edot-sdks/java/supported-technologies.md +++ b/docs/reference/edot-sdks/java/supported-technologies.md @@ -10,58 +10,42 @@ products: - id: observability - id: edot-java --- -# Technologies Supported by the EDOT Java Agent -The EDOT Java agent is a [distribution](https://opentelemetry.io/docs/concepts/distributions/) of -[OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) agent, it thus -inherits all the [supported (✅)](../../compatibility/nomenclature.md) technologies of the OpenTelemetry Java Instrumentation. +# Technologies supported by the EDOT Java Agent -## EDOT Collector / Elastic Stack versions +The EDOT Java agent is a [distribution](https://opentelemetry.io/docs/concepts/distributions/) of [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) agent. It inherits all the [supported](../../compatibility/nomenclature.md) technologies of the OpenTelemetry Java Instrumentation. -The EDOT Java agent sends data via the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support it is strongly recommended that you use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. +## EDOT Collector and Elastic Stack versions -See [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. +The EDOT Java agent sends data through the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. + +Refer to [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. :::{note} -> Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ *is supported*. +Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ is supported. ::: -## JVM Versions +## JVM versions -The EDOT Java agent supports **JVM (OpenJDK, OpenJ9) versions 8+** -This follows from the [OpenTelemetry supported JMVs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#jvms-and-operating-systems). +The EDOT Java agent supports JVM (OpenJDK, OpenJ9) versions 8+. This follows from the [OpenTelemetry supported JMVs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#jvms-and-operating-systems). -## Application Servers +## Application servers The EDOT Java agent supports [all the application servers documented by the OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#application-servers). -## Libraries & Frameworks Instrumentations +## Libraries and Frameworks instrumentations The EDOT Java agent supports [all the libraries and frameworks documented by the OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks). -Please note that [some supported technologies are disabled by default](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#disabled-instrumentations) -and need explicit configuration to be enabled. - -The EDOT Java agent also supports technologies listed here that are _not available_ in the [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation). - -See also the [EDOT Java agent configuration](./configuration.md#configuration-options) for defaults that might differ from the OpenTelemetry Java Instrumentation. - -## LLM instrumentations - -### OpenAI Client instrumentation +Note that [some supported technologies are deactivated by default](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#disabled-instrumentations) and need explicit configuration to be activated. -Instrumentation for the [official OpenAI Java Client](https://github.com/openai/openai-java). -The minimum supported OpenAI Java Client version is 1.1.0. +The EDOT Java agent also supports technologies listed here that are not available in the [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation). -This instrumentation supports: +Refer to the [EDOT Java agent configuration](./configuration.md#configuration-options) for defaults that might differ from the OpenTelemetry Java Instrumentation. -* Tracing for requests, including GenAI-specific attributes such as token usage -* Opt-In logging of OpenAI request and response content payloads +## OpenAI Client instrumentation -Configuration options: +The minimum supported version of the OpenAI Java Client is 1.1.0. This instrumentation supports: -| Option | default | description | -|-------------------------------------------------------|---------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `OTEL_INSTRUMENTATION_OPENAI_CLIENT_ENABLED` | `true` | enables or disable OpenAI instrumentation | -| `ELASTIC_OTEL_JAVA_INSTRUMENTATION_GENAI_EMIT_EVENTS` | value of `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | If set to `true`, the agent will generate log events for OpenAI requests and responses. Potentially sensitive content will only be included if `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` is `true` | -| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false` | If set to `true`, enables the capturing of OpenAI request and response content in the log events outputted by the agent. ↪ | +* Tracing for requests, including GenAI-specific attributes such as token usage. +* Opt-in logging of OpenAI request and response content payloads. diff --git a/docs/reference/edot-sdks/nodejs/supported-technologies.md b/docs/reference/edot-sdks/nodejs/supported-technologies.md index eea8b9df..2c504b12 100644 --- a/docs/reference/edot-sdks/nodejs/supported-technologies.md +++ b/docs/reference/edot-sdks/nodejs/supported-technologies.md @@ -11,40 +11,36 @@ products: - id: edot-nodejs --- -# Technologies Supported by the EDOT Node.js SDK +# Technologies supported by the EDOT Node.js SDK -## EDOT Collector / Elastic Stack versions +The EDOT Node.js agent is a [distribution](https://opentelemetry.io/docs/concepts/distributions/) of OpenTelemetry Node.js. It inherits all the [supported](../../compatibility/nomenclature.md) technologies of the OpenTelemetry Node.js. -The Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) sends data via the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support it is strongly recommended that you use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. +## EDOT Collector and Elastic Stack versions + +The Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) sends data through the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. :::{note} -Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ *is supported*. +Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ is supported. ::: -See [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. +Refer to [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. ## Node.js versions -EDOT Node.js supports **Node.js 18.19.0, 20.6.0, or later.** -This follows from the [OpenTelemetry JS supported runtimes](https://github.com/open-telemetry/opentelemetry-js#supported-runtimes). - - +EDOT Node.js supports Node.js 18.19.0, 20.6.0, or later. This follows from the [OpenTelemetry JS supported runtimes](https://github.com/open-telemetry/opentelemetry-js#supported-runtimes). ## TypeScript versions -To use this package, `@elastic/opentelemetry-node`, in TypeScript code requires: - -- **TypeScript 5.0.4 or later**, and -- using `"module": "node16"` (or "nodenext") in "tsconfig.json" to get support for handling the "exports" entry in package.json. This is so the `@elastic/opentelemetry-node/sdk` entry-point can be used. (See https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html#ecmascript-module-support-in-nodejs) +Usage of `@elastic/opentelemetry-node` in TypeScript code requires: +- TypeScript 5.0.4 or later +- Using `"module": "node16"` or "nodenext" in "tsconfig.json" to get support for handling the "exports" entry in package.json. This is so the `@elastic/opentelemetry-node/sdk` entry-point can be used. ## Instrumentations [instrumentations] -The following instrumentations are included in EDOT Node.js. All are enabled by default, except those noted "disabled by default". -🔹 marks instrumentations that differ between EDOT Node.js and upstream OTel JS, or that only exist in EDOT Node.js. +The following instrumentations are included in EDOT Node.js. All are turned on by default, except those noted _Turned off by default_. + +The 🔹 symbol marks instrumentations that differ between EDOT Node.js and upstream OTel JS, or that only exist in EDOT Node.js. | Name | Packages instrumented | Notes | |---|---|---| @@ -55,12 +51,12 @@ The following instrumentations are included in EDOT Node.js. All are enabled by | `@opentelemetry/instrumentation-cassandra-driver` | `cassandra-driver` version range `>=4.4.0 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-cassandra#readme) | | `@opentelemetry/instrumentation-express` | `express` version range `^4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express#readme) | | `@opentelemetry/instrumentation-fastify` | `fastify` version range `>=3 <5` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-fastify#readme), [disabled by default](#disabled-instrumentations) | -| `@opentelemetry/instrumentation-fs` | `fs` module for suppported Node.js versions | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-fs#readme), [disabled by default](#disabled-instrumentations) | +| `@opentelemetry/instrumentation-fs` | `fs` module for supported Node.js versions | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-fs#readme), [disabled by default](#disabled-instrumentations) | | `@opentelemetry/instrumentation-generic-pool` | `generic-pool` version range `2 - 2.3, ^2.4, >=3` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-generic-pool#readme) | | `@opentelemetry/instrumentation-graphql` | `graphql` version range `>=14.0.0 <17` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-graphql#readme) | | `@opentelemetry/instrumentation-grpc` | `@grpc/grpc-js` version range `^1.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc#readme) | | `@opentelemetry/instrumentation-hapi` | `@hapi/hapi >=17.0.0 <21` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-hapi#readme) | -| `@opentelemetry/instrumentation-http` | `http` module for suppported Node.js versions | [README](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http#readme) | +| `@opentelemetry/instrumentation-http` | `http` module for supported Node.js versions | [README](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http#readme) | | `@opentelemetry/instrumentation-ioredis` | `ioredis` version range `>=2 <6` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-ioredis#readme) | | `@opentelemetry/instrumentation-kafkajs` | `kafkajs` version range `>=0.1.0 <3` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-kafkajs#readme) | | `@opentelemetry/instrumentation-knex` | `knex` version range `>=0.10.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-knex#readme) | @@ -72,7 +68,7 @@ The following instrumentations are included in EDOT Node.js. All are enabled by | `@opentelemetry/instrumentation-mysql` | `mysql` version range `>=2.0.0 <3` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/plugins/node/opentelemetry-instrumentation-mysql#readme) | | `@opentelemetry/instrumentation-mysql2` | `mysql2` version range `>=1.4.2 <4` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/plugins/node/opentelemetry-instrumentation-mysql2#readme) | | `@opentelemetry/instrumentation-nestjs-core` | `@nestjs/core` version range `>=4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-nestjs-core#readme) | -| `@opentelemetry/instrumentation-net` | `net` module for suppported Node.js versions | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-net#readme) | +| `@opentelemetry/instrumentation-net` | `net` module for supported Node.js versions | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-net#readme) | | `@opentelemetry/instrumentation-pino` | `pino` version range `>=5.14.0 <10` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pino#readme) | | `@opentelemetry/instrumentation-pg` | `pg` version range `>=8 <9` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pg#readme) | | `@opentelemetry/instrumentation-redis-4` | `redis` version range `^4.0.0` | [README](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-redis-4#readme) | @@ -85,23 +81,22 @@ The following instrumentations are included in EDOT Node.js. All are enabled by ### LLM instrumentations -We can instrument the following LLM (Large Language Model) libraries with instrumentations implementing the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/): +EDOT Node.js can instrument the following Large Language Model (LLM) libraries with instrumentations implementing the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/): | SDK | Instrumentation | Traces | Metrics | Logs | Notes | |--------|-----------------|--------|---------|------|-------| | OpenAI | [@elastic/opentelemetry-instrumentation-openai](https://github.com/elastic/elastic-otel-node/tree/main/packages/instrumentation-openai#readme) | ✅ | ✅ | ✅ | (1) | -(1) Support for [chat](https://platform.openai.com/docs/api-reference/chat) and [embeddings](https://platform.openai.com/docs/api-reference/embeddings) API endpoints. +1. Support for [chat](https://platform.openai.com/docs/api-reference/chat) and [embeddings](https://platform.openai.com/docs/api-reference/embeddings) API endpoints. +### Deactivated instrumentations [disabled-instrumentations] -### Disabled instrumentations [disabled-instrumentations] +The following instrumentations are included in EDOT Node.js, but deactivated by default: -The following instrumentations are included in EDOT Node.js, but *disabled by default*: +- `@opentelemetry/instrumentation-fs` (Deactivated upstream in [open-telemetry/opentelemetry-js-contrib#2467](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2467).) +- `@opentelemetry/instrumentation-fastify` (Deprecated upstream and slated for removal. Refer to [open-telemetry/opentelemetry-js-contrib#2652](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2652)) -- `@opentelemetry/instrumentation-fs` (Disabled upstream in [open-telemetry/opentelemetry-js-contrib#2467](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2467).) -- `@opentelemetry/instrumentation-fastify` (Deprecated upstream and slated for removal. See [open-telemetry/opentelemetry-js-contrib#2652](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2652)) - -To enable these instrumentations, use the [`OTEL_NODE_ENABLED_INSTRUMENTATIONS` environment variable](./configuration.md#otel_node_disabledenabled_instrumentations-details). Make sure you list all the instrumentations you need for your service since only the ones in that list will be enabled. For example: +To turn on these instrumentations, use the [`OTEL_NODE_ENABLED_INSTRUMENTATIONS` environment variable](./configuration.md#otel_node_disabledenabled_instrumentations-details). Make sure you list all the instrumentations you need for your service since only the ones in that list will be activated. For example: ```bash export OTEL_EXPORTER_OTLP_ENDPOINT="https://my-deployment-abc123.ingest.us-west-2.aws.elastic.cloud" @@ -111,12 +106,11 @@ export OTEL_NODE_ENABLED_INSTRUMENTATIONS="fs,http,fastify" # only the ones in t node --import @elastic/opentelemetry-node my-service.js ``` -EDOT Node.js uses the upstream [`@opentelemetry/auto-instrumentations-node` package's set of instrumentations](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-instrumentations-node/README.md#supported-instrumentations) as a guide for instrumentations to include, exclude, or disable by default. This is to maximize compatibility between usage of EDOT Node.js and the vanilla OpenTelemetry JS SDK. - +EDOT Node.js uses the upstream [`@opentelemetry/auto-instrumentations-node` package set of instrumentations](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-instrumentations-node/README.md#supported-instrumentations) as a guide for instrumentations to include, exclude, or turn off by default. This is to maximize compatibility between usage of EDOT Node.js and the upstream OpenTelemetry JS SDK. -## Native Instrumentations +## Native instrumentations -"Native" instrumentation refers to OpenTelemetry instrumentation that is built into a library. When a library includes native OTel instrumentation, it will provide telemetry data to providers registered by a running OTel SDK. Native instrumentations of note are listed in the table below. To benefit from these instrumentations you only need to (a) use the library and (b) start the EDOT Node.js SDK: +Native instrumentation refers to OpenTelemetry instrumentation that is built into a library. When a library includes native OTel instrumentation, it provides telemetry data to providers registered by a running OTel SDK. Native instrumentations of note are listed in the following table. To benefit from these instrumentations you only need to use the library and start the EDOT Node.js SDK: ```bash node --import @elastic/opentelemetry-node my-app.js @@ -126,17 +120,15 @@ node --import @elastic/opentelemetry-node my-app.js |---|---| | `@elastic/elasticsearch` version range `>=8.15.0` | [Elasticsearch JavaScript Client docs](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/observability.html) | - ## ECMAScript Modules (ESM) -This Distro includes **limited and experimental** support for instrumenting [ECMAScript module (ESM) imports](https://nodejs.org/api/esm.html#modules-ecmascript-modules), i.e. modules that are loaded via `import ...` statements and `import('...')` (dynamic import). To enable ESM instrumentation, use `node --import @elastic/opentelemetry-node ...` to start the SDK. (Using `node --require @elastic/opentelemetry-node ...` will not enable ESM instrumentation. It is intended to signal that only CommonJS module usage should be instrumented.) +EDOT Node.js includes limited and experimental support for instrumenting [ECMAScript module (ESM) imports](https://nodejs.org/api/esm.html#modules-ecmascript-modules). For example modules that are loaded through `import ...` statements and `import('...')` (dynamic import). - +To activate ESM instrumentation, use `node --import @elastic/opentelemetry-node ...` to start the SDK. Using `node --require @elastic/opentelemetry-node ...` does not turn on ESM instrumentation. It is intended to signal that only CommonJS module usage should be instrumented. ### Limitations -* ESM instrumentation is only support for Node.js versions `^18.19.0 || >=20.6.0`. These are the versions that include `module.register()` support. Using the older `node --experimental-loader=...` option is not supported. -* Currently only a subset of instrumentations support ESM: `express`, `ioredis`, `koa`, `pg`, `pino`. See [this OpenTelemetry JS tracking issue](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/1942) for progress. +The following limitations apply to ESM instrumentation: + +* ESM instrumentation is only supported for Node.js versions `^18.19.0 || >=20.6.0`. These are the versions that include `module.register()` support. Using the older `node --experimental-loader=...` option is not supported. +* Currently, only a subset of instrumentations support ESM: `express`, `ioredis`, `koa`, `pg`, `pino`. Refer to [this OpenTelemetry JS tracking issue](https://github.com/open-telemetry/opentelemetry-js-contrib/issues/1942) for progress. diff --git a/docs/reference/edot-sdks/php/supported-technologies.md b/docs/reference/edot-sdks/php/supported-technologies.md index 08f6281d..c17a251f 100644 --- a/docs/reference/edot-sdks/php/supported-technologies.md +++ b/docs/reference/edot-sdks/php/supported-technologies.md @@ -11,68 +11,83 @@ products: - id: edot-php --- -# EDOT PHP supports the following technologies +# Technologies supported by EDOT PHP -## EDOT Collector / Elastic Stack versions +EDOT PHP is a [distribution](https://opentelemetry.io/docs/concepts/distributions/) of OpenTelemetry PHP. It inherits all the [supported](../../compatibility/nomenclature.md) technologies of the OpenTelemetry PHP. -EDOT PHP sends data via the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support it is strongly recommended that you use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. +## EDOT Collector and Elastic Stack versions + +EDOT PHP sends data through the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. :::{note} -Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ *is supported*. +Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ is supported. ::: -See [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. +Refer to [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. -## PHP Versions -- PHP 8.1 - 8.4 +## PHP versions -:::{note} -Unlike the upstream OpenTelemetry PHP agent, EDOT PHP supports extension-level instrumentation starting from PHP 8.1 (not just 8.2). -This allows you to capture **detailed traces** from libraries such as **cURL**, **PDO**, and **MySQLi**, even in PHP 8.1 environments. -::: +EDOT PHP supports PHP versions 8.1 to 8.4. + +Unlike the upstream OpenTelemetry PHP agent, EDOT PHP supports extension-level instrumentation starting from PHP 8.1. This allows you to capture detailed traces from libraries such as cURL, PDO, and MySQLi even in PHP 8.1 environments. + +## Supported PHP SAPIs + +The following SAPIs are supported: -## Supported PHP SAPI's - php-cli - php-fpm - php-cgi/fcgi - mod_php (prefork) -EDOT PHP supports all popular variations of using PHP in combination with a web server, such as Apache + mod_php, Apache + php_fpm or cgi, NGINX + php_fpm or cgi, and others. +EDOT PHP supports all popular variations of using PHP in combination with a web server, such as Apache with mod_php, Apache with php_fpm or cgi, NGINX with php_fpm or cgi, and others. + +## Supported operating systems + +The following operating systems are supported: +- Linux + - Architectures: x86_64 and ARM64 + - glibc-based systems: Packages available as DEB and RPM + - musl libc-based systems (Alpine Linux): Packages available as APK + +## Instrumented frameworks + +The following frameworks are supported: + +- Laravel versions 6.x, 7.x, 8.x, 9.x, 10.x, and v11.x +- Slim version 4.x + +## Instrumented libraries + +The following libraries are supported: + +- Curl versions 8.1 to 8.4 +- HTTP Async (php-http/httplug) version 2.x +- MySQLi versions 8.1 to 8.4 +- PDO versions 8.1 to 8.4 + +## Additional features and improvements +### Truly zero-config auto-instrumentation + +Unlike the upstream OpenTelemetry PHP agent, EDOT PHP works fully automatically. There is no need to modify your application code, add Composer packages, or adjust deployment scripts. Once the system package is installed, EDOT PHP automatically detects your application and injects the instrumentation code at runtime, without requiring manual integration. -## Supported Operating Systems -- **Linux** - - Architectures: **x86_64** and **ARM64** - - **glibc-based systems**: Packages available as **DEB** and **RPM** - - **musl libc-based systems (Alpine Linux)**: Packages available as **APK** +### Automatic Root/Transaction Span -## Instrumented Frameworks -- Laravel (v6.x/v7.x/v8.x/v9.x/v10.x/v11.x) -- Slim (v4.x) +EDOT PHP automatically creates the root span for each incoming request, providing a consistent entry point for trace data without requiring manual instrumentation. -## Instrumented Libraries -- Curl (v8.1 - v8.4) -- HTTP Async (php-http/httplug v2.x) -- MySQLi (v8.1 - v8.4) -- PDO (v8.1 - v8.4) +### Root/Transaction Span URL Grouping -## Extends the upstream OpenTelemetry PHP with additional features and improvements -- **Truly zero-config auto-instrumentation** - Unlike the upstream OpenTelemetry PHP agent, **EDOT PHP works fully automatically** — no need to modify your application code, add Composer packages, or adjust deployment scripts. - Once the system package is installed, EDOT PHP automatically detects your application and injects the instrumentation code at runtime, **without a need for manual integration**. +Transaction spans are grouped by URL patterns to reduce cardinality and improve readability in dashboards and trace views. -- **Automatic Root/Transaction Span** - Automatically creates the root span for each incoming request, providing a consistent entry point for trace data without requiring manual instrumentation. +### Inferred Spans (preview version) -- **Root/Transaction Span URL Grouping** - Groups transaction spans by URL patterns to reduce cardinality and improve readability in dashboards and trace views. +EDOT PHP automatically detects and generates spans for common operations like database queries or HTTP calls, even when no manual instrumentation is present. This feature is currently in preview. -- **Inferred Spans (preview version)** - Automatically detects and generates spans for common operations like database queries or HTTP calls, even when no manual instrumentation is present (currently in preview). +### Asynchronous data sending -- **Asynchronous data sending** - Sends telemetry data in the background to avoid impacting application performance, ensuring minimal latency and efficient resource usage. +Telemetry data is sent in the background to avoid impacting application performance. This ensures minimal latency and efficient resource usage. :::{note} -EDOT PHP supports background data transmission (non-blocking export), but **only when the exporter is set to `http/protobuf` (OTLP over HTTP)** — which is the default configuration. -If you change the exporter or the transport protocol (e.g., to gRPC or another format), telemetry data will be sent **synchronously**, potentially impacting request latency. +EDOT PHP supports background data transmission (non-blocking export), but only when the exporter is set to `http/protobuf` (OTLP over HTTP), which is the default configuration. +If you change the exporter or the transport protocol, for example to gRPC or another format, telemetry will be sent synchronously, potentially impacting request latency. ::: \ No newline at end of file diff --git a/docs/reference/edot-sdks/python/configuration.md b/docs/reference/edot-sdks/python/configuration.md index 661838dd..50fbbbf0 100644 --- a/docs/reference/edot-sdks/python/configuration.md +++ b/docs/reference/edot-sdks/python/configuration.md @@ -71,3 +71,11 @@ EDOT Python uses different defaults than OpenTelemetry Python for the following | Option(s) | Default | Description | |---|---|---| | `ELASTIC_OTEL_SYSTEM_METRICS_ENABLED` | `false` | When sets to `true`, sends *system namespace* metrics. | + +## LLM settings + +LLM instrumentations implement the following configuration options: + +| Option | default | description | +|-------------------------------------------------------|---------|:--------------------------| +| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false`| If set to `true`, enables the capturing of request and response content in the log events outputted by the agent. diff --git a/docs/reference/edot-sdks/python/supported-technologies.md b/docs/reference/edot-sdks/python/supported-technologies.md index dec6feed..6bb0d3a1 100644 --- a/docs/reference/edot-sdks/python/supported-technologies.md +++ b/docs/reference/edot-sdks/python/supported-technologies.md @@ -11,17 +11,19 @@ products: - id: edot-python --- -# Technologies Supported by the EDOT Python SDK +# Technologies supported by EDOT Python -## EDOT Collector / Elastic Stack versions +EDOT Python is a [distribution](https://opentelemetry.io/docs/concepts/distributions/) of OpenTelemetry Python. It inherits all the [supported](../../compatibility/nomenclature.md) technologies of the OpenTelemetry Python. -EDOT Python sends data via the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support it is strongly recommended that you use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. +## EDOT Collector and Elastic Stack versions + +EDOT Python sends data through the OpenTelemetry protocol (OTLP). While OTLP ingest works with later 8.16+ versions of the EDOT Collector, for full support use either [EDOT Collector](../../edot-collector/index.md) versions 9.x or [Elastic Cloud Serverless](https://www.elastic.co/guide/en/serverless/current/intro.html) for OTLP ingest. :::{note} -> Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ *is supported*. +Ingesting data from EDOT SDKs through EDOT Collector 9.x into Elastic Stack versions 8.18+ is supported. ::: -See [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. +Refer to [EDOT SDKs compatibility](../../compatibility/sdks.md) for support details. ## Python versions @@ -38,7 +40,7 @@ This follows the [OpenTelemetry Python Version Support](https://github.com/open- ## Instrumentations -We don't install instrumentations by default and we suggest to use our [edot-bootstrap](./setup/index.md#install-the-available-instrumentation) command to automatically install the available instrumentations. +Instrumentations are not installed by default. Use the [edot-bootstrap](./setup/index.md#install-the-available-instrumentation) command to automatically install the available instrumentations. | Name | Packages instrumented | Semantic conventions status | |---|---|---|---| @@ -96,35 +98,23 @@ We don't install instrumentations by default and we suggest to use our [edot-boo | [opentelemetry-instrumentation-wsgi](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-wsgi) | wsgi | migration The semantic conventions status tracks the stabilization of the semantic conventions used in the instrumentation: -- stable, means they are stable and are not expected to change -- development, means they are not stable yet and they may change in the future -- migration, means there may be configuration knobs to switch between different semantic conventions + +- Stable means they are stable and are not expected to change. +- Development means they are not stable yet and they may change in the future. +- Migration means there may be configuration knobs to switch between different semantic conventions. ### Native Elasticsearch instrumentation -Some libraries like the [Python Elasticsearch Client](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html) -natively supports OpenTelemetry instrumentation. +Some libraries like the [Python Elasticsearch Client](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html) natively supports OpenTelemetry instrumentation. -The [elasticsearch](https://elasticsearch-py.readthedocs.io/en/latest/) package got native OpenTelemetry support since version 8.13. +The [elasticsearch](https://elasticsearch-py.readthedocs.io/en/latest/) package has native OpenTelemetry support since version 8.13. ### LLM instrumentations -We can instrument the following LLM (Large Language Model) libraries with instrumentations implementing the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/): - -| **SDK** | **Instrumentation** | **Traces** | **Metrics** | **Logs** | **Notes** | -|-----------------------------|----------------------------------------------|------------|-------------|----------|-----------| -| OpenAI | [elastic-opentelemetry-instrumentation-openai](https://github.com/elastic/elastic-otel-python-instrumentations/blob/main/instrumentation/elastic-opentelemetry-instrumentation-openai) | ✅ | ✅ | ✅ | 1. | -| AWS SDK for Python (Boto3) | [opentelemetry-instrumentation-botocore](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-botocore) | ✅ | ✅ | ✅ | 2. | -| Google Cloud AI Platform | [opentelemetry-instrumentation-vertexai](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-vertexai) | ✅ | 🚧 | ✅ | 3. | - -1. Support for sync and async [chat completions create](https://platform.openai.com/docs/guides/text?api-mode=chat) API and [embeddings](https://platform.openai.com/docs/guides/embeddings?lang=python) API. -2. Support for [Bedrock Runtime](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-runtime.html) [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html), [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html), [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) and [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html) APIs. A subset of models are traced in InvokeModel and InvokeModelWithStreaming API, see [botocore instrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-botocore#bedrock-runtime). -3. Instrumentation supports tracing and sending events for synchronous API calls, and currently doesn't support async APIs and streaming calls yet. - -#### Configuration - -These instrumentations implement the following configuration options: +You can instrument the following LLM (Large Language Model) libraries with instrumentations implementing the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/): -| Option | default | description | -|-------------------------------------------------------|---------|:--------------------------| -| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false`| If set to `true`, enables the capturing of request and response content in the log events outputted by the agent. +| **SDK** | **Instrumentation** | **Traces** | **Metrics** | **Logs** | **Notes** | +|-----------------------------|----------------------------------------------|--------------|-----------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| OpenAI | [elastic-opentelemetry-instrumentation-openai](https://github.com/elastic/elastic-otel-python-instrumentations/blob/main/instrumentation/elastic-opentelemetry-instrumentation-openai) | Supported | Supported | Supported | Supports sync and async [chat completions create](https://platform.openai.com/docs/guides/text?api-mode=chat) API and [embeddings](https://platform.openai.com/docs/guides/embeddings?lang=python) API. | +| AWS SDK for Python (Boto3) | [opentelemetry-instrumentation-botocore](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-botocore) | Supported | Supported | Supported | Supports [Bedrock Runtime](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-runtime.html) APIs like [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html), [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html), [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html), and [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html). A subset of models are traced in InvokeModel and InvokeModelWithStreaming API. See [botocore instrumentation](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-botocore#bedrock-runtime). | +| Google Cloud AI Platform | [opentelemetry-instrumentation-vertexai](https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation-genai/opentelemetry-instrumentation-vertexai) | Supported | Experimental | Supported | Instrumentation supports tracing and sending events for synchronous API calls. Currently, it doesn't support async APIs and streaming calls. | From bc51c17e4ffb7b3d3ebd41faaef6be3651e7abd3 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 13 May 2025 14:13:04 +0200 Subject: [PATCH 07/14] Troubleshooting --- .../edot-sdks/dotnet/troubleshooting.md | 142 +++++++----------- .../edot-sdks/java/troubleshooting.md | 100 ++++++------ .../edot-sdks/nodejs/troubleshooting.md | 72 +++------ .../edot-sdks/php/troubleshooting.md | 106 ++++++------- .../edot-sdks/python/troubleshooting.md | 50 +++--- 5 files changed, 186 insertions(+), 284 deletions(-) diff --git a/docs/reference/edot-sdks/dotnet/troubleshooting.md b/docs/reference/edot-sdks/dotnet/troubleshooting.md index 0e230566..2ea491d9 100644 --- a/docs/reference/edot-sdks/dotnet/troubleshooting.md +++ b/docs/reference/edot-sdks/dotnet/troubleshooting.md @@ -11,67 +11,26 @@ products: # Troubleshooting the EDOT .NET SDK -Use the information in this section to troubleshoot common problems. As a first step, ensure your stack is -compatible with the [supported technologies](.//supported-technologies.md) for EDOT .NET and the OpenTelemetry SDK. +Use the information in this section to troubleshoot common problems. As a first step, make sure your stack is compatible with the [supported technologies](.//supported-technologies.md) for EDOT .NET and the OpenTelemetry SDK. -Don’t worry if you can’t figure out what the problem is; we’re here to help. If you are an existing -Elastic customer with a support contract, please create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). -If not, post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/elastic-otel-dotnet/issues). +If you have an Elastic support contract, create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). If you don't, post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/elastic-otel-dotnet/issues). -For most problems, such as when no data is received in your Elastic Observability backend, it’s a good idea to first check -the EDOT .NET logs which will provide initialization details and OpenTelemetry SDK events. If you don’t see anything suspicious - in the EDOT .NET logs (no warning or error), it’s recommended to switch the log level to `Trace` for further investigation. +## Obtain EDOT .NET diagnostic logs -## Known issues - -### Missing log records - -The upstream SDK is (currently) [not spec-compliant](https://github.com/open-telemetry/opentelemetry-dotnet/issues/4324) regarding -the deduplication of attributes when exporting log records. When a log is created within multiple scopes, each scope may store information -using the same logical key. In this situation, attributes will be duplicated in the exported data. This situation is most likely to present when -logging in to the scope of a request and when the `OpenTelemetryLoggerOptions.IncludeScopes` option is enabled. ASP.NET Core adds the -`RequestId` to multiple scopes. We therefore recommend not enabling `IncludeScopes` until this is fixed in the SDK. When using the -EDOT Collector or Managed OTLP endpoint in serverless, non-compliant log records will fail to be ingested. - -EDOT .NET currently emits a warning if it detects the use of `IncludeScopes` in ASP.NET Core scenarios. +For most problems, such as when you don't see data in your Elastic Observability backend, first check the EDOT .NET logs. These logs show initialization details and OpenTelemetry SDK events. If you don't see any warnings or errors in the EDOT .NET logs, switch the log level to `Trace` to investigate further. -It is also possible for this to occur even when `IncludeScopes` is false. The following code will also result in duplicate -attributes and the potential for lost log records. - -```csharp -Logger.LogInformation("Eat your {fruit} {fruit} {fruit}!", "apple", "banana", "mango"); -``` - -To avoid this scenario, ensure each placeholder uses a unique name. e.g. - -```csharp -Logger.LogInformation("Eat your {fruit1} {fruit2} {fruit3}!", "apple", "banana", "mango"); -``` - -## Obtaining EDOT .NET diagnostic logs - -The Elastic Distribution of OpenTelemetry .NET includes built-in diagnostic logging, which can be directed -to a file, STDOUT and, in common scenarios, an `ILogger` instance. EDOT .NET also observes the built-in diagnostics events -from the upstream OpenTelemetry SDK and includes those in its logging output. The log output may be collected -and used to diagnose issues locally during development and when engaging with Elastic support channels. +The Elastic Distribution of OpenTelemetry .NET includes built-in diagnostic logging. You can direct logs to a file, STDOUT, or, in common scenarios, an `ILogger` instance. EDOT .NET also observes the built-in diagnostics events from the upstream OpenTelemetry SDK and includes those in its logging output. You can collect the log output and use it to diagnose issues locally during development or when working with Elastic support channels. ## ASP.NET Core (generic host) logging integration -When building applications based on the generic host, such as those created by the [ASP.NET Core](https://learn.microsoft.com/aspnet/core/introduction-to-aspnet-core) -and [worker service](https://learn.microsoft.com/dotnet/core/extensions/workers) templates, the Elastic Distribution -of OpenTelemetry .NET will attempt to automatically register with the built-in logging components when using -the `IHostApplicationBuilder.AddElasticOpenTelemetry` extension method to register EDOT .NET. +When you build applications based on the generic host, such as those created by the [ASP.NET Core](https://learn.microsoft.com/aspnet/core/introduction-to-aspnet-core) and [worker service](https://learn.microsoft.com/dotnet/core/extensions/workers) templates, the Elastic Distribution of OpenTelemetry .NET will try to automatically register with the built-in logging components when you use the `IHostApplicationBuilder.AddElasticOpenTelemetry` extension method to register EDOT .NET. ```csharp var builder = WebApplication.CreateBuilder(args); builder.AddElasticOpenTelemetry(); ``` -In this scenario, EDOT .NET will attempt to access an available `ILoggerFactory` and create an `ILogger`, logging -to the event category `Elastic.OpenTelemetry`. This will be registered as the additional logger for the EDOT .NET -diagnostics unless a user-provided `ILogger` has already been configured. This ensures that EDOT .NET and OpenTelemetry -SDK logs are written for the application's configured logging providers. In ASP.NET Core, this includes the console logging -provider and will result in logs such as the following: +In this scenario, EDOT .NET tries to access an available `ILoggerFactory` and create an `ILogger`, logging to the event category `Elastic.OpenTelemetry`. EDOT .NET will register this as the additional logger for its diagnostics unless you have already configured a user-provided `ILogger`. This ensures that EDOT .NET and OpenTelemetry SDK logs are written for your application's configured logging providers. In ASP.NET Core, this includes the console logging provider and results in logs such as the following: ``` info: Elastic.OpenTelemetry[0] @@ -88,14 +47,11 @@ info: Microsoft.Hosting.Lifetime[0] Hosting environment: Development ``` -In the preceding log output, informational level logging is enabled as the default for this application. The -output can be controlled by configuring the log levels. +In the preceding log output, informational level logging is enabled as the default for this application. You can control the output by configuring the log levels. ### Configuring the log level -Logs sent to the integrated `Microsoft.Extensions.Logging` library can be -[configured](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#configure-logging) in several ways. -A common choice is to use the `appsettings.json` file to configure log-level filters for specific categories. +You can [configure](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#configure-logging) logs sent to the integrated `Microsoft.Extensions.Logging` library in several ways. A common choice is to use the `appsettings.json` file to configure log-level filters for specific categories. ```json { @@ -110,20 +66,16 @@ A common choice is to use the `appsettings.json` file to configure log-level fil } ``` -In the preceding code, the `Elastic.OpenTelemetry` has been filtered to only emit log entries when they have the -`Warning` log level or a higher severity. This overrides the `Default` configuration of `Information`. +In the preceding code, you have filtered `Elastic.OpenTelemetry` to only emit log entries when they have the `Warning` log level or a higher severity. This overrides the `Default` configuration of `Information`. ## Enable global file logging -Integrated logging is helpful because it requires little to no setup. The logging infrastructure is not present -by default in some application types, such as console applications. EDOT .NET also offers a global file logging -feature, which is the easiest way to get diagnostics and debug information. File logging is required when engaging -Elastic support where trace logs will be requested. +Integrated logging is helpful because it requires little to no setup. The logging infrastructure is not present by default in some application types, such as console applications. EDOT .NET also offers a global file logging feature, which is the easiest way for you to get diagnostics and debug information. You must enable file logging when you work with Elastic support, as trace logs will be requested. -Specifying at least one of the following environment variables will ensure that EDOT .NET logs into a file +Specify at least one of the following environment variables to make sure that EDOT .NET logs into a file. `OTEL_LOG_LEVEL` _(optional)_: -The log level at which the profiler should log. Valid values are +Set the log level at which the profiler should log. Valid values are * trace * debug @@ -132,26 +84,21 @@ The log level at which the profiler should log. Valid values are * error * none -The default value is `information`. More verbose log levels like `trace` and `debug` can affect the runtime -performance of profiler auto instrumentation, so are recommended _only_ for diagnostics purposes. +The default value is `information`. More verbose log levels like `trace` and `debug` can affect the runtime performance of profiler auto instrumentation, so use them _only_ for diagnostics purposes. :::{note} -If `ELASTIC_OTEL_LOG_TARGETS` is not explicitly set to include `file`, global file logging will only -be enabled when configured with `trace` or `debug`. +If you don't explicitly set `ELASTIC_OTEL_LOG_TARGETS` to include `file`, global file logging will only be enabled when you configure it with `trace` or `debug`. ::: `OTEL_DOTNET_AUTO_LOG_DIRECTORY` _(optional)_: -The directory in which to write log files. If unset, defaults to +Set the directory in which to write log files. If you don't set this, the default is: * `%USERPROFILE%\AppData\Roaming\elastic\elastic-otel-dotnet` on Windows * `/var/log/elastic/elastic-otel-dotnet` on Linux * `~/Library/Application Support/elastic/elastic-otel-dotnet` on OSX > ::::{important} -> The user account under which the profiler process runs must have permission to -> write to the destination log directory. Specifically, ensure that when running -> on IIS, the https://learn.microsoft.com/en-us/iis/manage/configuring-security/application-pool-identities[AppPool identity] -> has write permissions in the target directory. +> Make sure the user account under which the profiler process runs has permission to write to the destination log directory. Specifically, when you run on IIS, ensure that the [AppPool identity](https://learn.microsoft.com/en-us/iis/manage/configuring-security/application-pool-identities) has write permissions in the target directory. > :::: `ELASTIC_OTEL_LOG_TARGETS` _(optional)_: @@ -161,20 +108,17 @@ A semi-colon separated list of targets for profiler logs. Valid values are * stdout * none -The default value is `file` if `OTEL_DOTNET_AUTO_LOG_DIRECTORY` is set or `OTEL_LOG_LEVEL` is set to `trace` or `debug`. +The default value is `file` if you set `OTEL_DOTNET_AUTO_LOG_DIRECTORY` or set `OTEL_LOG_LEVEL` to `trace` or `debug`. -## Advanced Troubleshooting +## Advanced troubleshooting -### Diagnosing initialisation (bootstrap) issues +### Diagnosing initialization or bootstrap issues -No log file is generated if the EDOT for .NET fails before fully bootstrapping its internal components. In such -circumstances, an additional logger may be provided for diagnostic purposes. Alternatively, the `STDOUT` log target -can be enabled. +If EDOT for .NET fails before fully bootstrapping its internal components, it won't generate a log file. In such circumstances, you can provide an additional logger for diagnostic purposes. Alternatively, you can enable the `STDOUT` log target. #### Providing an additional application logger -An additional `ILogger` that will be used by EDOT .NET to log pre-bootstrap events can be provided by -creating an instance of `ElasticOpenTelemetryOptions`. +You can provide an additional `ILogger` that EDOT .NET will use to log pre-bootstrap events by creating an instance of `ElasticOpenTelemetryOptions`. ```csharp using Elastic.OpenTelemetry; @@ -188,7 +132,7 @@ using ILoggerFactory loggerFactory = LoggerFactory.Create(static builder => .AddConsole(); }); -Ilogger logger = loggerFactory.CreateLogger("EDOT"); +ILogger logger = loggerFactory.CreateLogger("EDOT"); var options = new ElasticOpenTelemetryOptions { @@ -199,21 +143,13 @@ using var sdk = OpenTelemetrySdk.Create(builder => builder .WithElasticDefaults(options)); ``` -This example adds the console logging provider, but any provider may be included here. -To use this sample code, a dependency on the `Microsoft.Extensions.Logging.Console` -[NuGet package](https://www.nuget.org/packages/microsoft.extensions.logging.console) is required +This example adds the console logging provider, but you can include any provider here. To use this sample code, add a dependency on the `Microsoft.Extensions.Logging.Console` [NuGet package](https://www.nuget.org/packages/microsoft.extensions.logging.console). -An `ILoggerFactory` is created and configured. In this example, -the `Elastic.OpenTelemetry` category is configured to capture trace logs, which is the most -verbose option. This is the best choice when diagnosing initialisation issues. +You create and configure an `ILoggerFactory`. In this example, you configure the `Elastic.OpenTelemetry` category to capture trace logs, which is the most verbose option. This is the best choice when you diagnose initialization issues. -The `ILoggerFactory` is used to create an `Ilogger`, which is then assigned to the -`ElasticOpenTelemetryOptions.AdditionalLogger` property. Once the `ElasticOpenTelemetryOptions` -is passed into the `WithElasticDefaults` method, the provided logger can be used to -capture bootstrap logs. +You use the `ILoggerFactory` to create an `ILogger`, which you then assign to the `ElasticOpenTelemetryOptions.AdditionalLogger` property. Once you pass the `ElasticOpenTelemetryOptions` into the `WithElasticDefaults` method, the provided logger can capture bootstrap logs. -To simplify the preceding code a little, it's also possible to configure the `ElasticOpenTelemetryOptions` -with an `ILoggerFactory` instance that EDOT .NET can use to create its own logger. +To simplify the preceding code, you can also configure the `ElasticOpenTelemetryOptions` with an `ILoggerFactory` instance that EDOT .NET can use to create its own logger. ```csharp using var loggerFactory = LoggerFactory.Create(static builder => @@ -230,4 +166,28 @@ var options = new ElasticOpenTelemetryOptions using var sdk = OpenTelemetrySdk.Create(builder => builder .WithElasticDefaults(options)); +``` + +## Known issues + +The following known issues affect EDOT .NET. + +### Missing log records + +The upstream SDK currently does not [comply with the spec](https://github.com/open-telemetry/opentelemetry-dotnet/issues/4324) regarding the deduplication of attributes when exporting log records. When you create a log within multiple scopes, each scope may store information using the same logical key. In this situation, the exported data will have duplicated attributes. + +You are most likely to see this when you log in the scope of a request and enable the `OpenTelemetryLoggerOptions.IncludeScopes` option. ASP.NET Core adds the `RequestId` to multiple scopes. We recommend that you don't enable `IncludeScopes` until the SDK fixes this. When you use the EDOT Collector or Managed OTLP endpoint in serverless, non-compliant log records will fail to be ingested. + +EDOT .NET currently emits a warning if it detects that you use `IncludeScopes` in ASP.NET Core scenarios. + +This can also happen even when you set `IncludeScopes` to false. The following code will also result in duplicate attributes and the potential for lost log records. + +```csharp +Logger.LogInformation("Eat your {fruit} {fruit} {fruit}!", "apple", "banana", "mango"); +``` + +To avoid this scenario, make sure each placeholder uses a unique name. For example: + +```csharp +Logger.LogInformation("Eat your {fruit1} {fruit2} {fruit3}!", "apple", "banana", "mango"); ``` \ No newline at end of file diff --git a/docs/reference/edot-sdks/java/troubleshooting.md b/docs/reference/edot-sdks/java/troubleshooting.md index 43615ea2..5cd7adc0 100644 --- a/docs/reference/edot-sdks/java/troubleshooting.md +++ b/docs/reference/edot-sdks/java/troubleshooting.md @@ -13,105 +13,104 @@ products: # Troubleshooting the EDOT Java Agent -The sections below are in the order you should follow, unless you have already identified the section you need. +Use the information in this section to troubleshoot common problems. As a first step, make sure your stack is compatible with the [supported technologies](.//supported-technologies.md) for EDOT Java and the OpenTelemetry SDK. -This guide assumes you have tested the other components in the route from application+agent to Elastic Observability (eg collector, Elasticsearch, and Kibana) and that the problem has been isolated to the application+agent. +If you need help and you're an existing Elastic customer with a support contract, create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). Other users can post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/elastic-otel-node/issues) -## General +## General troubleshooting -Ensure you have set a service name (eg `-Dotel.service.name=Service1` or environment variable `OTEL_SERVICE_NAME` set to `Service1`) otherwise by default the data (traces, metrics, logs) will be sent to `unknown_service_java` - you may be getting data but it may all be under that service +Make you have set a service name, for example `-Dotel.service.name=Service1` or the environment variable `OTEL_SERVICE_NAME` set to `Service1`. Otherwise, by default the data will be sent to `unknown_service_java`. You may be getting data but it may all be under that service. ## Connectivity to endpoint -Check _from_ the host/VM/pod/container/image running the app, that connectivity is available to the collector. +Check from the host, VM, pod, container, or image running the app that connectivity is available to the Collector. -The examples here use a default URL `http://127.0.0.1:4318/, which you should replace with the endpoint you are using: +The following examples use a default URL, `http://127.0.0.1:4318/, which you should replace with the endpoint you are using: - OpenTelemetry or EDOT collector without authentication: `curl -i http://127.0.0.1:4318/v1/traces -X POST -d '{}' -H content-type:application/json` - OpenTelemetry or EDOT collector with API key authentication: `curl -i http://127.0.0.1:4318/v1/traces -X POST -d '{}' -H content-type:application/json -H "Authorization:ApiKey "` -The collector should produce output similar to +The Collector should produce output similar to the following: + ``` {"partialSuccess":{}} ``` -## Is it the agent? +## Agent troubleshooting + +Determine if the issue is related to the agent by following these steps: -Determine if the issue is related to the agent by +1. Start the application with no agent and see if the issue is not present. Observe if the issue is again present when restarting with the agent. +2. Check end-to-end connectivity without the agent by running one or more of the example apps in https://github.com/elastic/elastic-otel-java/blob/main/examples/troubleshooting/README.md . These use the OpenTelemetry SDK rather than the auto-instrumentation. They can confirmation that the issue is specific to the agent or can otherwise identify that the issue is something else. -1. Starting the application with no agent and seeing if the issue is not present, but then the issue is again present when restarting with the agent -2. Check end-to-end connectivity without the agent by running one or more of the example apps in https://github.com/elastic/elastic-otel-java/blob/main/examples/troubleshooting/README.md . These use the OpenTelemetry SDK rather than the auto-instrumentation, ie there is no agent present, and create traces, metrics and logs, so provide confirmation that the issue is specific to the agent or can otherwise identify that the issue is something else +## Agent debug output -## Agent DEBUG +Turn on debug output with `-Dotel.javaagent.debug=true` or by setting the `OTEL_JAVAAGENT_DEBUG` environment variable to `true`. -Debug output is enabled with `-Dotel.javaagent.debug=true` or environment variable `OTEL_JAVAAGENT_DEBUG` to `true`. +After debug is activated, look for: -Once debug is enabled, look for: -- Errors and exceptions -- For the expected traces or metrics - or lack of them (maybe the [technology isn't instrumented?](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md)) +- Errors and exceptions. +- For the expected traces or metrics, or the lack of them. Perhaps the [technology isn't instrumented](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md). -## Does agent requires access to or modification of application code ? +## Access or modification of application code -No, the agent modifies the Java application binaries in bytecode form and does not requires original code nor -recompiling or re-packaging the application. +The agent modifies the Java application binaries in bytecode form and does not requires original code nor recompiling or re-packaging the application. -## How to disable the agent ? +## How to deactivate the agent -There are two ways to disable the instrumentation agent: +There are two ways to deactivate the instrumentation agent: -- remove `-javaagent:` JVM argument -- set `OTEL_JAVAAGENT_ENABLED` environment variable or `otel.javaagent.enabled` Java system property to `false` +- Remove the `-javaagent:` JVM argument. +- Set the `OTEL_JAVAAGENT_ENABLED` environment variable or the `otel.javaagent.enabled` Java system property to `false`. In both cases you need to restart the JVM. -## How to partially enable or disable the agent ? +## Partial activation or deactivation of the agent + +You can partially deactivate the agent, or only selectively activate a limited set of instrumentations by following instructions in the [upstream documentation](https://opentelemetry.io/docs/zero-code/java/agent/disable/). -It is possible to partially disable the agent, or to only selectively enable a limited set of instrumentations -by following instructions in the [upstream documentation](https://opentelemetry.io/docs/zero-code/java/agent/disable/). +## Check if EDOT is attached to a running JVM -## How to know if EDOT is attached to a running JVM ? +There are a few ways you can detect if the agent has been attached to a JVM: -There are a few ways we can detect if the agent has been attached to a JVM -- in JVM logs, agent startup log message (see [below](#how-to-identify-the-version-of-edot-agent-)) might be included -- in JVM arguments `ps -ef|grep javaagent` -- in environment variables, for example `JAVA_TOOL_OPTIONS`, for example by inspecting the output of `export|grep javaagent` +- In JVM logs, agent startup log message (see [below](#how-to-identify-the-version-of-edot-agent-)) might be included. +- In JVM arguments, Run `ps -ef|grep javaagent`. +- In environment variables, for example `JAVA_TOOL_OPTIONS`. Check by inspecting the output of `export|grep javaagent`. -## How to identify the version of EDOT agent ? +## Identify the version of EDOT agent When the agent starts, a log message in the standard error provides the agent version: + ``` INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.2.3 ``` -In addition, the `-javaagent:` JVM argument can provide the path to the agent file name, which _might_ also contain +In addition, the `-javaagent:` JVM argument can provide the path to the agent file name, which might also contain the agent version, for example `-javaagent:elastic-otel-javaagent-1.2.3.jar`. -Executing the agent jar as an application with `java -jar elastic-otel-javaagent.jar` will provide the agent version on standard output, -which could be relevant to use when the jar file has been renamed. +Executing the agent jar as an application with `java -jar elastic-otel-javaagent.jar` provides the agent version on standard output, which could be relevant to use when the jar file has been renamed. -Also, it is also possible to inspect the `Implementation-Version` entry in `META-INF/MANIFEST.MF` file of the agent jar, -for example with `unzip -p elastic-otel-javaagent.jar META-INF/MANIFEST.MF|grep 'Implementation-Version'` +Also, you can inspect the `Implementation-Version` entry in `META-INF/MANIFEST.MF` file of the agent jar, for example with `unzip -p elastic-otel-javaagent.jar META-INF/MANIFEST.MF|grep 'Implementation-Version'`. -## What are the versions of the OpenTelemetry upstream dependencies ? +## Versions of the OpenTelemetry upstream dependencies -Because EDOT Java is a distribution of [OpenTelemetry Java instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation), -it includes the following dependencies: +Because EDOT Java is a distribution of [OpenTelemetry Java instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation), it includes the following dependencies: - [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) - [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java) - [Semantic Conventions Java mappings](https://github.com/open-telemetry/semantic-conventions-java) - [OpenTelemetry Java Contrib](https://github.com/open-telemetry/opentelemetry-java-contrib) -The versions of those included in EDOT is usually aligned with the OpenTelemetry Java Instrumentation, for reference we -provide in the [release notes](https://github.com/elastic/elastic-otel-java/releases) details of versions included in each release. +The versions of those included in EDOT are usually aligned with the OpenTelemetry Java Instrumentation. For reference, check the [release notes](https://github.com/elastic/elastic-otel-java/releases) details of versions included in each release. ## When and how to update EDOT The general recommendation is to update EDOT agent to the latest version when possible to benefit from: -- bug fixes and technical improvements -- support of new features and instrumentation -- evolution of semantic conventions -- frequent and regular updates usually makes reviewing and handling changes easier. + +- Bug fixes and technical improvements. +- Support of new features and instrumentation. +- Evolution of semantic conventions. +- Frequent and regular updates usually makes reviewing and handling changes easier. Updating to the latest EDOT version involves reviewing changes of the included dependencies: @@ -120,16 +119,15 @@ Updating to the latest EDOT version involves reviewing changes of the included d - [Semantic Conventions Java mappings](https://github.com/open-telemetry/semantic-conventions-java) - [OpenTelemetry Java Contrib](https://github.com/open-telemetry/opentelemetry-java-contrib) -In order to review each of those individually, you can use the [EDOT release notes](https://github.com/elastic/elastic-otel-java/releases) -for links to the respective versions of each component. +To review each of those individually, you can use the [EDOT release notes](https://github.com/elastic/elastic-otel-java/releases) for links to the respective versions of each component. ### OpenTelemetry API/SDK update -In order to implement manual instrumentation, some applications use the OpenTelemetry API and/or SDK which allows them -to capture custom spans, metrics or even send data without any instrumentation agent. +To implement manual instrumentation, some applications use the OpenTelemetry API and/or SDK which allows them to capture custom spans, metrics or even send data without any instrumentation agent. Updates of the OpenTelemetry API/SDK in the application and the EDOT Java agent can be done independently. -- EDOT Java is backward-compatible with all previous versions of OpenTelemetry API/SDK + +- EDOT Java is backward-compatible with all previous versions of OpenTelemetry API/SDK. - Using a more recent version of API/SDK than the one in EDOT should usually work without problem, however to ensure maximum compatibility keeping OpenTelemetry API/SDK version ≤ EDOT OpenTelemetry API/SDK version is recommended. ### How to update diff --git a/docs/reference/edot-sdks/nodejs/troubleshooting.md b/docs/reference/edot-sdks/nodejs/troubleshooting.md index 8c490fdf..097beddb 100644 --- a/docs/reference/edot-sdks/nodejs/troubleshooting.md +++ b/docs/reference/edot-sdks/nodejs/troubleshooting.md @@ -15,23 +15,17 @@ products: Use the information on this page to troubleshoot issues using EDOT Node.js. -If you need help and you're an existing Elastic customer with a support contract, please create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). Other users can post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/elastic-otel-node/issues). +If you need help and you're an existing Elastic customer with a support contract, create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). Other users can post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/elastic-otel-node/issues). +As a first step, review the [supported technologies](./supported-technologies.md) to ensure your application is supported by the SDK. Are you using a Node.js version that the SDK supports? Are the versions of your dependencies in the [supported version range](./supported-technologies.md#instrumentations) to be instrumented? -## Is your app compatible with the SDK's supported technologies? +## Set a service name -First, review the [supported technologies](./supported-technologies.md) to ensure your application is supported by the SDK. Are you using a Node.js version that the SDK supports? Are the versions of your dependencies in the [supported version range](./supported-technologies.md#instrumentations) to be instrumented? +Make sure you have set a service name set using `OTEL_SERVICE_NAME=my-service` or through the `OTEL_RESOURCE_ATTRIBUTES=service.name=my-service` environment variables. Otherwisem by default the data is sent to the `unknown_service:node` service: you might be getting data but it might all be under that service. +## Check connectivity -## Have you set a service name? - -Ensure you have set a service name (via `OTEL_SERVICE_NAME=my-service`, or via `OTEL_RESOURCE_ATTRIBUTES=service.name=my-service`) otherwise by default the data (traces, metrics, logs) will be sent to the `unknown_service:node` service -- you may be getting data but it may all be under that service. - - -## Can the application reach the OTLP endpoint? - -Check *from* the host/VM/pod/container running your application, that connectivity is available to the collector. -Run: +Check from the host, VM, pod, container running your application, that connectivity is available to the Collector. Run the following command: ```bash curl -i $ELASTIC_OTLP_ENDPOINT \ @@ -47,7 +41,7 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey Zm9vO...mJhcg==" ... ``` -then you would run: +Then you would run: ```bash curl -i https://my-deployment-abc123.ingest.us-west-2.aws.elastic.cloud \ @@ -55,7 +49,7 @@ curl -i https://my-deployment-abc123.ingest.us-west-2.aws.elastic.cloud \ -H "Authorization: ApiKey Zm9vO...mJhcg==" ``` -If that works correctly, you should expect to see output similar to: +If that works correctly, you should expect to see output similar to the following: ``` HTTP/1.1 200 OK @@ -67,32 +61,30 @@ Content-Length: 21 ``` -## Is the SDK causing an application issue? +## Deactivate the SDK -If your application has an issue, but you are not sure if the EDOT Node.js SDK -could be the cause, try disabling the SDK. +If your application has an issue, but you are not sure if the EDOT Node.js SDK could be the cause, try deactivating the SDK. -You can exclude the SDK by not starting it with your application: +You can exclude the SDK by not starting it with your application by running the following command: ```bash node my-app.js # instead of 'node --import @elastic/opentelemetry-node my-app.js' ``` -or by setting the `OTEL_SDK_DISABLED` environment variable: +Or by setting the `OTEL_SDK_DISABLED` environment variable: ```bash export OTEL_SDK_DISABLED=true node --import @elastic/opentelemetry-node my-app.js ``` - ## SDK diagnostic logs [sdk-diagnostic-logs] -Next, enable verbose diagnostic / debug logging from EDOT Node.js: +Turn on verbose diagnostic or debug logging from EDOT Node.js: -1. Set the `OTEL_LOG_LEVEL` environment varible to `verbose`. -2. Restart your application, and reproduce the issue. (Note: If the issue is about not seeing telemetry that you expect to see, be sure to exercise your application -- e.g. send it HTTP requests -- so that telemetry data is generated.) -3. Gather *the full verbose log from application start* until after the issue was reproduced. +1. Set the `OTEL_LOG_LEVEL` environment variable to `verbose`. +2. Restart your application, and reproduce the issue. If the issue is about not seeing telemetry that you expect to see, be sure to use your application so that telemetry data is generated. +3. Gather the full verbose log from application start until after the issue was reproduced. The start of the diagnostic log will look something like this: @@ -111,32 +103,12 @@ The start of the diagnostic log will look something like this: ``` Look for warnings (`"level":40`) or errors (`"level":50`) in the log output that might indicate an issue. -(This log output will be invaluable in Elastic support requests or for developers in support requests.) - - -## Getting support - -If you are stuck, you can ask for help. If you're an existing Elastic customer with a support contract, please create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). Other users can post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/elastic-otel-node/issues). - -When opening an issue: - -1. By far the best way to help get a quick resolution of your issue is if you can provide a small **reproduction** case. For example, create a small GitHub repository that reproduces the same problem you are seeing. We understand that creating a small reproduction is not always possible. -2. **Describe your application/service/system architecture** as accurately as possible. -3. Include as much **[diagnostic log output](#sdk-diagnostic-logs)** as possible. - -:::{warning} -Though an effort is made to avoid it, verbose/debug diagnostic logs **can include sensitive information**. Therefore it is **not** recommended that the full log is included in public forums or GitHub issues. (This is less of a concern for private Elastic customer support.) -::: - -## How to disable the SDK? - -Set the `OTEL_SDK_DISABLED` environment variable to `true`, and restart your application. -## How to disable an instrumentation? +## Deactivate an instrumentation -Set the [`OTEL_NODE_DISABLED_INSTRUMENTATIONS`](./configuration.md#otel_node_disabledenabled_instrumentations-details) environment variable. +To deactivate an instrumentation, set the [`OTEL_NODE_DISABLED_INSTRUMENTATIONS`](./configuration.md#otel_node_disabledenabled_instrumentations-details) environment variable. -For example, to disable `@opentelemetry/instrumentation-net` and `@opentelemetry/instrumentation-dns`: +For example, to deactivate `@opentelemetry/instrumentation-net` and `@opentelemetry/instrumentation-dns` run the following commands: ```bash export OTEL_NODE_DISABLED_INSTRUMENTATIONS=dns,net @@ -144,11 +116,11 @@ export OTEL_NODE_DISABLED_INSTRUMENTATIONS=dns,net node --import @elastic/opentelemetry-node my-app.js ``` -## How to tell if EDOT Node.js is running? +## Check if EDOT Node.js is running -Look for "start Elastic Distribution of OpenTelemetry Node.js" in the application log. +Look for `start Elastic Distribution of OpenTelemetry Node.js` in the application log. -As it is starting, EDOT Node.js always logs (at the "info" level) a preamble to indicate that it has started. For example, it looks like this: +As it is starting, EDOT Node.js always logs at the "info" level a preamble to indicate that it has started. For example: ```json {"name":"elastic-otel-node","level":30,"preamble":true,"distroVersion":"0.7.0","env":{"os":"darwin 24.3.0","arch":"arm64","runtime":"Node.js v18.20.4"},"msg":"start Elastic Distribution of OpenTelemetry Node.js","time":"2025-03-27T22:14:08.288Z"} diff --git a/docs/reference/edot-sdks/php/troubleshooting.md b/docs/reference/edot-sdks/php/troubleshooting.md index 3a371025..ab62bf76 100644 --- a/docs/reference/edot-sdks/php/troubleshooting.md +++ b/docs/reference/edot-sdks/php/troubleshooting.md @@ -11,116 +11,102 @@ products: - id: edot-php --- -# Troubleshooting the EDOT PHP Agent +# Troubleshooting the EDOT PHP agent -Is something not working as expected? -Don't worry if you can't figure out what the problem is; we’re here to help! -As a first step, make sure your application is compatible with the [technologies supported by EDOT PHP](./supported-technologies.md). +Use the information on this page to troubleshoot issues using EDOT PHP. -If you're an existing Elastic customer with a support contract, please create a ticket in the -[Elastic Support portal](https://support.elastic.co/customers/s/login/). -Other users can post in the [APM discuss forum](https://discuss.elastic.co/c/apm). +If you need help and you're an existing Elastic customer with a support contract, create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). Other users can post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/elastic-otel-node/issues). -## Enable logging +As a first step, review the [supported technologies](./supported-technologies.md) to ensure your application is supported by the agent. Are you using a PHP version that EDOT PHP supports? Are the versions of your dependencies in the supported version range to be instrumented? -In diagnosing issues with the agent's operation, logs play a key role. A detailed explanation of the logging configuration options can be found in the [configuration documentation](./configuration.md#logging-configuration). +## Turn on logging -In most cases, setting the logging level to `debug` is sufficient. In extreme cases, `trace` can be used, but keep in mind that the amount of generated data may be significant. +When diagnosing issues with the agent's operation, logs play a key role. You can find a detailed explanation of the logging configuration options in [Configuration](./configuration.md#logging-configuration). -Additionally, it is recommended to enable logging for OpenTelemetry components, for example, as shown in the example below using an environment variable. Logs from OpenTelemetry components will be directed to the same output configured for EDOT logs. +In most cases, setting the logging level to `debug` is sufficient. You can also use `trace` can be used, but keep in mind that the amount of generated data might be significant. + +Additionally, turn on logging for OpenTelemetry components, for example as shown in the following example . Logs from OpenTelemetry components are directed to the same output configured for EDOT logs. ``` export OTEL_LOG_LEVEL=DEBUG ``` :::{note} -Please upload your complete debug logs to a service like [GitHub Gist](https://gist.github.com) so that we can analyze the problem. Logs should include everything from when the application starts up until the first request executes. It is important to note that logs may contain sensitive data — be sure to review and sanitize them before sharing. +Upload your complete debug logs to a service like [GitHub Gist](https://gist.github.com) so that Elastic support can analyze the problem. Logs should include everything from when the application starts up until the first request executes. Logs might contain sensitive data: make sure to review and sanitize them before sharing. ::: -## Disable the Agent +## Turn off the agent -In the unlikely event the agent causes disruptions to a production application, -you can disable the agent while you troubleshoot. +If you suspect that the agent might be causing disruptions to a production application, you can deactivate the agent while you troubleshoot. -You can disable the agent by setting [`elastic_otel.enabled`](./configuration.md#general-configuration) to `false`. +To deactivate the agent, set the [`elastic_otel.enabled`](./configuration.md#general-configuration) setting to `false`. :::{note} -You'll need to restart your application for the changes to apply. +You need to restart your application for the changes to apply. ::: - ## Agent is not instrumenting code +If the agent doesn't seem to be instrumenting code from your application, try the following actions. + ### Native OTLP serializer issues -If you're experiencing issues where **no spans, logs, or metrics** are being sent — or you encounter log messages like: +If you're experiencing issues where no spans, logs, or metrics are being sent, or if you encounter log messages like the following: ```bash Failed to serialize spans/logs/metrics batch... ``` -— it may be due to a failure in the native OTLP Protobuf serializer. - -The native serializer is enabled by default for maximum performance, but in rare cases, it may encounter incompatibilities with certain environments or data. - -To confirm whether this is the cause, try disabling the native serializer using the following environment variable: +This might be due to a failure in the native OTLP Protobuf serializer. The native serializer is activated by default for maximum performance, but in rare cases it might encounter incompatibilities with certain environments or data. To confirm whether this is the cause, try turning off the native serializer using the following environment variable: ```bash export ELASTIC_OTEL_NATIVE_OTLP_SERIALIZER_ENABLED=false ``` -Restart your application and check if spans/logs/metrics start appearing correctly. +Restart your application and check if spans, logs, or metrics start appearing correctly. :::{note} -When disabled, the agent falls back to a PHP-based serializer, which has lower performance. +When turned off, the agent falls back to a PHP-based serializer, which has lower performance. ::: ### `open_basedir` PHP configuration option -If you see a similar entry in the agent log, this indicates an incorrect open_basedir configuration. -For more details please see [limitations documentation](./setup/limitations.md#open_basedir-php-configuration-option). - - -`EDOT PHP bootstrap file (...php/bootstrap_php_part.php) is located outside of paths allowed by open_basedir ini setting.` - -## Collection of diagnostic information - -For a more detailed analysis of issues, it is necessary to collect diagnostic information. The agent allows for the automatic collection of such information - all data will be saved to the file specified in the configuration. +If you see a similar entry in the agent log, this indicates an incorrect `open_basedir` configuration. For more details, refer to [Limitations](./setup/limitations.md#open_basedir-php-configuration-option). -There are two possible ways to enable this feature: - -- By php.ini - To enable this feature, you need to modify the php.ini file (or 99-elastic.ini) and provide the path to the file where the data will be saved, f.ex: ``` -elastic_otel.debug_diagnostic_file=/tmp/php_diags_%p_%t.txt +EDOT PHP bootstrap file (...php/bootstrap_php_part.php) is located outside of paths allowed by open_basedir ini setting. ``` -- By environment variable. You can also enable information collection using the environment variable `ELASTIC_OTEL_DEBUG_DIAGNOSTIC_FILE`. It must be exported or directly specified when running php process. +## Collection of diagnostic information + +For a more detailed analysis of issues, you might need to collect diagnostic information. The agent allows for the automatic collection of such information: all data is saved to the file specified in the configuration. -Example of calling php-cli script: -```bash -ELASTIC_OTEL_DEBUG_DIAGNOSTIC_FILE=/tmp/php_diags_%p_%t.txt php test.php -``` +There are two possible ways to turn on diagnostic information: -Remember, the provided file path must be writable by the PHP process. +- By editing the `php.ini` file: Modify the `php.ini` file, or `99-elastic.ini`, to provide the path to the file where the data will be saved, For example: -If there are multiple PHP processes in your system, we allow you to specify directives in the diagnostic file name. This way, the files will remain unique and won't be overwritten. + ``` + elastic_otel.debug_diagnostic_file=/tmp/php_diags_%p_%t.txt + ``` -- `%p` - In this place, the agent will substitute the process identifier. +- By setting an environment variable. The `ELASTIC_OTEL_DEBUG_DIAGNOSTIC_FILE` environment variable must be exported or directly specified when running PHP process. For example: -- `%t` - In this place, the agent will substitute the UNIX timestamp. + ```bash + ELASTIC_OTEL_DEBUG_DIAGNOSTIC_FILE=/tmp/php_diags_%p_%t.txt php test.php + ``` -:::{warning} IMPORTANT -After setting the path, remember to _fully restart the process_ for which you are collecting diagnostic information. This may vary depending on the context, such as PHP, PHP-FPM, Apache, or PHP-CGI. Diagnostic information will be recorded after the first HTTP request is made or at the beginning of script execution for PHP-CLI. + The provided file path must be writable by the PHP process. If there are multiple PHP processes in your system, you can specify directives in the diagnostic file name. This way, the files remain unique and won't be overwritten. -Please also be aware that the information contained in the output file may include sensitive data, such as passwords, security tokens or environment variables from your system. Make sure to review the data and mask sensitive information before sharing the file publicly. + - `%p` - In this place, the agent substitutes the process identifier. + - `%t` - In this place, the agent substitutes the UNIX timestamp. -After collecting diagnostic information, remember to disable this feature and restore the previous configuration in php.ini or the environment variable. +:::{warning} +After setting the path, remember to fully restart the process for which you are collecting diagnostic information. This might vary depending on the context, such as PHP, PHP-FPM, Apache, or PHP-CGI. Diagnostic information will be recorded after the first HTTP request is made or at the beginning of script execution for PHP-CLI. Also be aware that the information contained in the output file may include sensitive data, such as passwords, security tokens or environment variables from your system. After collecting diagnostic information, remember to disable this feature and restore the previous configuration in php.ini or the environment variable. ::: - -What information will be collected: +The following information is collected: - Process identifier and parent process identifier - User identifier of the worker process @@ -129,22 +115,22 @@ What information will be collected: - Process memory information and memory maps (`/proc/{id}/maps` and `/proc/{id}/smaps_rollup`) - Process status information (`/proc/{id}/status`) -## Enabling Debugging for Instrumented Functions +## Turn on debugging for instrumented functions -EDOT allows detailed diagnostics of arguments passed to instrumented functions. This makes it possible to verify whether the data used by the instrumented application is correctly analyzed by the instrumentation code. +EDOT can collect detailed diagnostics of arguments passed to instrumented functions. Use them to verify whether the data used by the instrumented application is correctly analyzed by the instrumentation code. -This feature can be enabled using an environment variable: +To turn on debugging for instrumented function, set the following environment variable: ```bash ELASTIC_OTEL_DEBUG_PHP_HOOKS_ENABLED=true ``` -## Enabling instrumentation of the entire application code +## Turn on instrumentation of all the application code -For diagnostic purposes (*this feature is not suitable for production use*), EDOT allows instrumentation of the entire code. This enables tracking function calls throughout the processing of an entire request or script. It provides better insight into the application's behavior and can help diagnose issues. +For diagnostic purposes outside of production environments, EDOT allows instrumenting the entire code of your application. This allows tracking function calls throughout the processing of an entire request or script and provides better insight into the application's behavior. -This feature can be enabled using an environment variable: +To turn on debugging for instrumented function, set the following environment variable: ```bash ELASTIC_OTEL_DEBUG_INSTRUMENT_ALL=true diff --git a/docs/reference/edot-sdks/python/troubleshooting.md b/docs/reference/edot-sdks/python/troubleshooting.md index 3ab7fd44..3c0193c7 100644 --- a/docs/reference/edot-sdks/python/troubleshooting.md +++ b/docs/reference/edot-sdks/python/troubleshooting.md @@ -13,60 +13,46 @@ products: # Troubleshooting the EDOT Python Agent -Below are some resources and tips for troubleshooting and debugging the Elastic Distribution of OpenTelemetry Python (EDOT Python). +Use the information on this page to troubleshoot issues using EDOT Python. -- [Easy Fixes](#easy-fixes) -- [Disable EDOT](#easy-fixes) +If you need help and you're an existing Elastic customer with a support contract, create a ticket in the [Elastic Support portal](https://support.elastic.co/customers/s/login/). Other users can post in the [APM discuss forum](https://discuss.elastic.co/c/apm) or [open a GitHub issue](https://github.com/elastic/elastic-otel-node/issues). -## Easy Fixes +As a first step, review the [supported technologies](./supported-technologies.md) to ensure your application is supported by the agent. Are you using a Python version that EDOT Python supports? Are the versions of your dependencies in the supported version range to be instrumented? -Before you try anything else, go through the following sections to ensure that -EDOT Python is configured correctly. This is not an exhaustive list, but rather -a list of common problems that users run into. +## General troubleshooting + +Follow these recommended actions to make sure that EDOT Python is configured correctly. ### Debug and development modes -Most frameworks support a debug mode. Generally, this mode is intended for -non-production environments and provides detailed error messages and logging of -potentially sensitive data. So enabling instrumentation in debug mode is not advised and may pose privacy and security issues in recording -sensitive data. +Most frameworks support a debug mode. This mode is intended for non-production environments and provides detailed error messages and logging of potentially sensitive data. Turning on instrumentation in debug mode is not advised and might pose privacy and security issues in recording sensitive data. #### Django -Django applications running with the Django `runserver` need to use the `--noreload` parameter in order to be instrumented with `opentelemetry-instrument`. -Remember that you also need to set the `DJANGO_SETTINGS_MODULE` environment variable pointing to the application settings module. +Django applications running with the Django `runserver` must use the `--noreload` parameter to be instrumented with `opentelemetry-instrument`. You also need to set the `DJANGO_SETTINGS_MODULE` environment variable pointing to the application settings module. #### FastAPI -FastAPI application started with `fastapi dev` requires the reloader to be disabled with `--no-reload` in order to be instrumented with `opentelemetry-instrument`. +FastAPI application started with `fastapi dev` requires the reloader to be turned off with `--no-reload` to be instrumented with `opentelemetry-instrument`. #### Flask -Flask applications running in debug mode will require to disable the reloader in order to being traced, see [OpenTelemetry zero code documentation](https://opentelemetry.io/docs/zero-code/python/example/#instrumentation-while-debugging). - -## Disable EDOT +Flask applications running in debug mode require to turn off the reloader to be traced. Refer to [OpenTelemetry zero code documentation](https://opentelemetry.io/docs/zero-code/python/example/#instrumentation-while-debugging). -In the unlikely event EDOT Python causes disruptions to a production application, you can disable it while you troubleshoot. +## Turn off EDOT -To disable the underlying OpenTelemetry SDK you set the following environment variable `OTEL_SDK_DISABLED=true`. +In the unlikely event EDOT Python causes disruptions to a production application, you can turn it off while you troubleshoot. To turn off the underlying OpenTelemetry SDK, set the `OTEL_SDK_DISABLED` environment variable to `true`. -If only a subset of instrumentation are causing disruptions you can disable them with the `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` -environment variable. It accepts a list of comma separated instrumentations to disable, see [OpenTelemetry zero code documentation](https://opentelemetry.io/docs/zero-code/python/configuration/#disabling-specific-instrumentations) +If only a subset of instrumentation are causing disruptions, turn them off using the `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` environment variable. The variable accepts a list of comma-separated instrumentations. Refer to [OpenTelemetry zero code documentation](https://opentelemetry.io/docs/zero-code/python/configuration/#disabling-specific-instrumentations). ## Missing logs -Enabling the Python logging module auto-instrumentation with `OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true` calls the -[logging.basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig) method that will make your own application calls -to it a no-op. The side effect of this is that you won't see your application logs in the console anymore. - -If you are already shipping logs by other means you don't need to enable this. +Activating the Python logging module auto-instrumentation with `OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true` calls the [logging.basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig) method that makes your own application calls to it a no-op. The side effect of this is that you won't see your application logs in the console. If you are already shipping logs by other means, you don't need to turn this on. -## Are semantic convention stable yet? +## Check stability of semantic conventions -Unfortunately not yet and so you should expect some changes between versions in order to stabilize them. For some semantic conventions -like HTTP there is a migration path but the conversion to stable HTTP semantic conventions is not done yet for all the instrumentations. +For some semantic conventions, like HTTP, there is a migration path, but the conversion to stable HTTP semantic conventions is not done yet for all the instrumentations. -## Does EDOT Python require access to or modification of application code ? +## Access or modification of application code -EDOT Python is distributed as a Python package and so must be installed in the same environment as your application. Once it is -available in the path we can auto-instrument your application without changing the application code. +EDOT Python is distributed as a Python package and so must be installed in the same environment as your application. Once it is available in the path, it can auto-instrument your application without changing the application code. From dbe680ab75f1cb6a993777d86f71ffa1c551c6fa Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Tue, 13 May 2025 15:45:28 +0200 Subject: [PATCH 08/14] Remaining docs --- .../edot-sdks/dotnet/configuration.md | 90 +++--- docs/reference/edot-sdks/dotnet/index.md | 1 + .../edot-sdks/dotnet/setup/aspnet.md | 37 +-- .../edot-sdks/dotnet/setup/console.md | 76 ++--- .../edot-sdks/dotnet/setup/edot-defaults.md | 128 +++------ .../reference/edot-sdks/dotnet/setup/index.md | 117 +++----- .../edot-sdks/dotnet/setup/worker-services.md | 89 +++--- .../edot-sdks/dotnet/setup/zero-code.md | 13 +- .../dotnet/supported-technologies.md | 3 +- .../edot-sdks/dotnet/troubleshooting.md | 1 + .../reference/edot-sdks/java/configuration.md | 2 +- docs/reference/edot-sdks/java/features.md | 55 ++-- docs/reference/edot-sdks/java/overhead.md | 61 ++-- docs/reference/edot-sdks/java/setup/index.md | 59 ++-- docs/reference/edot-sdks/java/setup/k8s.md | 39 +-- .../edot-sdks/nodejs/configuration.md | 2 +- .../reference/edot-sdks/nodejs/setup/index.md | 45 ++- docs/reference/edot-sdks/nodejs/setup/k8s.md | 267 +++++++++--------- docs/reference/edot-sdks/php/configuration.md | 55 ++-- docs/reference/edot-sdks/php/overhead.md | 36 ++- docs/reference/edot-sdks/php/setup/index.md | 80 +++--- .../edot-sdks/php/setup/limitations.md | 10 +- .../edot-sdks/python/configuration.md | 10 +- docs/reference/edot-sdks/python/overhead.md | 12 +- .../reference/edot-sdks/python/setup/index.md | 66 ++--- docs/reference/edot-sdks/python/setup/k8s.md | 32 ++- .../python/setup/manual-instrumentation.md | 37 +-- 27 files changed, 600 insertions(+), 823 deletions(-) diff --git a/docs/reference/edot-sdks/dotnet/configuration.md b/docs/reference/edot-sdks/dotnet/configuration.md index 9ccfee8c..7bc57540 100644 --- a/docs/reference/edot-sdks/dotnet/configuration.md +++ b/docs/reference/edot-sdks/dotnet/configuration.md @@ -1,5 +1,6 @@ --- navigation_title: Configuration +description: Configure the Elastic Distribution of OpenTelemetry .NET (EDOT .NET) to send data to Elastic. applies_to: stack: serverless: @@ -10,7 +11,7 @@ products: - id: edot-dotnet --- -# Configuring the EDOT .NET SDK +# Configure the EDOT .NET SDK Configure the Elastic Distribution of OpenTelemetry .NET (EDOT .NET) to send data to Elastic. @@ -19,32 +20,25 @@ Configure the Elastic Distribution of OpenTelemetry .NET (EDOT .NET) to send dat Configure the OpenTelemetry SDK using the mechanisms listed in the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/net/automatic/configuration/), including: -* Setting [environment variables](#environment-variables) -* Using the [`IConfiguration` integration](#iconfiguration-integration) -* [Manually configuring](#manual-configuration) EDOT .NET +* Setting [environment variables](#environment-variables). +* Using the [`IConfiguration` integration](#iconfiguration-integration). +* [Manually configuring](#manual-configuration) EDOT .NET. -Configuration options set manually in code take precedence over environment variables, and -environment variables take precedence over configuration options set using the `IConfiguration` system. +Configuration options set manually in code take precedence over environment variables, and environment variables take precedence over configuration options set using the `IConfiguration` system. ### Environment variables -EDOT .NET can be configured using environment variables. This is a cross-platform way to configure EDOT .NET and is especially -useful in containerized environments. +You can configure EDOT .NET using environment variables. This is a cross-platform way to configure EDOT .NET and is especially useful in containerized environments. -Environment variables are read at startup and can be used to configure EDOT .NET. For details of the various EDOT-specific options -available and their corresponding environment variable names, see [Configuration options](#configuration-options). +Environment variables are read at startup and can be used to configure EDOT .NET. For details of the various EDOT-specific options available and their corresponding environment variable names, see [Configuration options](#configuration-options). -All OpenTelemetry environment variables from the upstream SDK may also be used to configure the SDK behavior for features -such as resources, samples and exporters. +All OpenTelemetry environment variables from the upstream SDK may also be used to configure the SDK behavior for features such as resources, samples and exporters. ### IConfiguration integration -In applications that use the [".NET generic host"](https://learn.microsoft.com/dotnet/core/extensions/generic-host), such as -[ASP.NET Core](https://learn.microsoft.com/aspnet/core/introduction-to-aspnet-core) and -[worker services](https://learn.microsoft.com/dotnet/core/extensions/workers), EDOT .NET can be configured using the `IConfiguration` integration. +In applications that use the [".NET generic host"](https://learn.microsoft.com/dotnet/core/extensions/generic-host), such as [ASP.NET Core](https://learn.microsoft.com/aspnet/core/introduction-to-aspnet-core) and [worker services](https://learn.microsoft.com/dotnet/core/extensions/workers), EDOT .NET can be configured using the `IConfiguration` integration. -When using an `IHostApplicationBuilder` in modern ASP.NET Core applications, the `AddElasticOpenTelemetry` extension method -enables EDOT .NET and configuration from `IHostApplicationBuilder.Configuration` is passed in automatically. +When using an `IHostApplicationBuilder` in modern ASP.NET Core applications, the `AddElasticOpenTelemetry` extension method turns on EDOT .NET and configuration from `IHostApplicationBuilder.Configuration` is passed in automatically. For example: ```csharp var builder = WebApplication.CreateBuilder(args); @@ -53,9 +47,7 @@ var builder = WebApplication.CreateBuilder(args); builder.AddElasticOpenTelemetry(); ``` -By default, at this stage, the configuration will be populated from the default configuration sources, -including the `appsettings.json` file(s) and command-line arguments. You may use these sources to define -the configuration for the Elastic Distribution of OpenTelemetry .NET. +By default, at this stage the configuration is populated from the default configuration sources, including the `appsettings.json` file(s) and command-line arguments. You can use these sources to define the configuration for the Elastic Distribution of OpenTelemetry .NET. For example, you can define the configuration for the Elastic Distribution of OpenTelemetry .NET in the `appsettings.json` file: @@ -70,14 +62,12 @@ For example, you can define the configuration for the Elastic Distribution of Op ``` :::{note} -This example sets the file log directory to `C:\Logs` which enables diagnostic file logging. +This example sets the file log directory to `C:\Logs` which activates diagnostic file logging. ::: -Configuration parsed from the `Elastic:OpenTelemetry` section of the `IConfiguration` instance will be -bound to the `ElasticOpenTelemetryOptions` instance used to configure EDOT .NET. +Configuration parsed from the `Elastic:OpenTelemetry` section of the `IConfiguration` instance is bound to the `ElasticOpenTelemetryOptions` instance used to configure EDOT .NET. -In situations (such as console applications) where the application may not depend on the hosting APIs, but -uses the dependency injection APIs instead, an `IConfiguration` instance can be passed in manually. +In situations where the application might not depend on the hosting APIs, but uses the dependency injection APIs instead, an `IConfiguration` instance can be passed in manually. This is usually the case with console applications. For example: ```csharp var configuration = new ConfigurationBuilder() @@ -91,18 +81,15 @@ var services = new ServiceCollection(); services.AddElasticOpenTelemetry(configuration); ``` -To learn more about the Microsoft configuration system, see -[Configuration in ASP.NET Core](https://learn.microsoft.com/aspnet/core/fundamentals/configuration). +To learn more about the Microsoft configuration system, see [Configuration in ASP.NET Core](https://learn.microsoft.com/aspnet/core/fundamentals/configuration). ### Manual configuration In all other scenarios, you can configure EDOT .NET manually in code. -Create an instance of `ElasticOpenTelemetryOptions` and pass it to an overload of the `WithElasticDefaults` extension methods -available on the `IHostApplicationBuilder`, the `IServiceCollection` and the specific signal providers such as `TracerProviderBuilder`. +Create an instance of `ElasticOpenTelemetryOptions` and pass it to an overload of the `WithElasticDefaults` extension methods available on the `IHostApplicationBuilder`, the `IServiceCollection` and the specific signal providers such as `TracerProviderBuilder`. -For example, in traditional console applications, you can configure the -Elastic Distribution of OpenTelemetry .NET like this: +For example, in traditional console applications, you can configure the Elastic Distribution of OpenTelemetry .NET like this: ```csharp using OpenTelemetry; @@ -125,8 +112,7 @@ using var sdk = OpenTelemetrySdk.Create(builder => builder ## Configuration options -Because the Elastic Distribution of OpenTelemetry .NET (EDOT .NET) is an extension of the -[OpenTelemetry .NET SDK](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation), it supports both: +Because the Elastic Distribution of OpenTelemetry .NET (EDOT .NET) is an extension of the [OpenTelemetry .NET SDK](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation), it supports both: * General OpenTelemetry SDK configuration options * Elastic-specific configuration options that are only available when using EDOT .NET @@ -141,12 +127,10 @@ EDOT .NET supports the following Elastic-specific options. #### `LogDirectory` -* _Type_: String -* _Default_: `string.Empty` +* Type: String +* Default: `string.Empty` -A string specifying the output directory where the Elastic Distribution of OpenTelemetry .NET will write diagnostic log files. -When not provided, no file logging will occur. Each new .NET process will create a new log file in the -specified directory. +A string specifying the output directory where the Elastic Distribution of OpenTelemetry .NET writes diagnostic log files. When not provided, no file logging occurs. Each new .NET process creates a new log file in the specified directory. | Configuration method | Key | |---|---| @@ -155,12 +139,10 @@ specified directory. #### `LogLevel` -* _Type_: String -* _Default_: `Information` +* Type: String +* Default: `Information` -Sets the logging level for EDOT .NET. - -Valid options: `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace` and `None` (`None` disables the logging). +Sets the logging level for EDOT .NET. Valid options are `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace`, and `None`. `None` disables the logging. | Configuration method | Key | |---|---| @@ -169,14 +151,12 @@ Valid options: `Critical`, `Error`, `Warning`, `Information`, `Debug`, `Trace` a #### `LogTargets` -* _Type_: String -* _Default_: `Information` +* Type: String +* Default: `Information` -A comma-separated list of targets for log output. When global logging is unconfigured (a log directory or -target is not specified) this defaults to `none`. When the instrumented application is running -within a container, this defaults to direct logs to `stdout`. Otherwise, defaults to `file`. +A comma-separated list of targets for log output. When global logging is not configured (a log directory or target is not specified) this defaults to `none`. When the instrumented application is running within a container, this defaults to direct logs to `stdout`. Otherwise defaults to `file`. -Valid options: `file`, `stdout` and `none` (`None` disables the logging). +Valid options are `file`, `stdout` and `none`. `None` disables the logging. | Configuration method | Key | |---|---| @@ -185,8 +165,8 @@ Valid options: `file`, `stdout` and `none` (`None` disables the logging). #### `SkipOtlpExporter` -* _Type_: Bool -* _Default_: `false` +* Type: Bool +* Default: `false` Allows EDOT .NET to be used with its defaults, but without enabling the export of telemetry data to an OTLP endpoint. This can be useful when you want to test applications without sending telemetry data. @@ -198,12 +178,10 @@ an OTLP endpoint. This can be useful when you want to test applications without #### `SkipInstrumentationAssemblyScanning` -* _Type_: Bool -* _Default_: `false` +* Type: Bool +* Default: `false` -Allows EDOT .NET to be used without the instrumentation assembly scanning feature enabled. This -prevents the automatic registration of instrumentation from referenced [OpenTelemetry contrib](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) -instrumentation packages. +Allows EDOT .NET to be used without the instrumentation assembly scanning feature turned on. This prevents the automatic registration of instrumentation from referenced [OpenTelemetry contrib](https://github.com/open-telemetry/opentelemetry-dotnet-contrib) instrumentation packages. | Configuration method | Key | |---|---| diff --git a/docs/reference/edot-sdks/dotnet/index.md b/docs/reference/edot-sdks/dotnet/index.md index ceb75772..5d308ae5 100644 --- a/docs/reference/edot-sdks/dotnet/index.md +++ b/docs/reference/edot-sdks/dotnet/index.md @@ -1,5 +1,6 @@ --- navigation_title: EDOT .NET +description: The Elastic Distribution of OpenTelemetry (EDOT) .NET provides an extension of the OpenTelemetry SDK for .NET, configured for the best experience with Elastic Observability. applies_to: stack: serverless: diff --git a/docs/reference/edot-sdks/dotnet/setup/aspnet.md b/docs/reference/edot-sdks/dotnet/setup/aspnet.md index 796205ec..42fa3544 100644 --- a/docs/reference/edot-sdks/dotnet/setup/aspnet.md +++ b/docs/reference/edot-sdks/dotnet/setup/aspnet.md @@ -1,5 +1,6 @@ --- navigation_title: ASP.NET +description: EDOT .NET can be used with ASP.NET applications by registering the OpenTelemetry SDK TelemetryHttpModule. applies_to: stack: serverless: @@ -12,9 +13,9 @@ products: # Set up EDOT .NET for ASP.NET applications on .NET Framework -EDOT .NET can be used with ASP.NET applications by registering the OpenTelemetry SDK TelemetryHttpModule. +You can use EDOT .NET with ASP.NET applications by registering the OpenTelemetry SDK TelemetryHttpModule. -## Installing the NuGet packages +## Install the NuGet packages To get started with the Elastic Distribution of OpenTelemetry .NET, add the `Elastic.OpenTelemetry` [NuGet package](https://www.nuget.org/packages/Elastic.OpenTelemetry) reference to your project file: @@ -27,24 +28,17 @@ reference to your project file: Replace the `` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry). ::: -EDOT .NET includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the OpenTelemetry SDK package to your project directly. However, -you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. +EDOT .NET includes a transitive dependency on the OpenTelemetry SDK, so you do not need to add the OpenTelemetry SDK package to your project directly. However, +you can explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. -For ASP.NET applications, you will also need to install the contrib instrumentation library. Add the -`OpenTelemetry.Instrumentation.AspNet` [NuGet package](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet) -reference to your project file: +For ASP.NET applications, you also need to install the contrib instrumentation library. Add the `OpenTelemetry.Instrumentation.AspNet` [NuGet package](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet) reference to your project file: ```xml ``` :::{note} -Replace the `` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry). -::: - -:::{note} -If you use the Visual Studio NuGet Package Manager or the .NET CLI to install this package, you will need to allow pre-release -package versions. +Replace the `` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry). If you use the Visual Studio NuGet Package Manager or the .NET CLI to install this package, you will need to allow prerelease package versions. ::: ## Modify web.config @@ -106,21 +100,16 @@ namespace AspNetFramework The preceding code: 1. Imports the required types from the `OpenTelemetry` namespace. -1. Creates an instance of the `OpenTelemetrySdk` using its factory `Create` method. -1. Configures the `IOpenTelemetryBuilder` by passing a lambda. -1. Enables EDOT .NET and its [opinionated defaults](edot-defaults.md) by calling `WithElasticDefaults` on the `IOpenTelemetryBuilder`. -1. Calls `ConfigureResource` to configure the name for the service. +2. Creates an instance of the `OpenTelemetrySdk` using its factory `Create` method. +3. Configures the `IOpenTelemetryBuilder` by passing a lambda. +4. Enables EDOT .NET and its [opinionated defaults](edot-defaults.md) by calling `WithElasticDefaults` on the `IOpenTelemetryBuilder`. +5. Calls `ConfigureResource` to configure the name for the service. -By default, EDOT .NET uses instrumentation assembly scanning and will detect the `OpenTelemetry.Instrumentation.AspNet` -instrumentation, registering it with the OpenTelemetry SDK. Traces for ASP.NET requests will automatically be observed -and exported over OTLP without further configuration. +By default, EDOT .NET uses instrumentation assembly scanning and will detect the `OpenTelemetry.Instrumentation.AspNet` instrumentation, registering it with the OpenTelemetry SDK. Traces for ASP.NET requests are automatically observed and exported over OTLP without further configuration. ## Configure environment variables -When calling `OpenTelemetrySdk.Create` a dedicated `IServiceCollection` and `IServiceProvider` will be created for the -SDK and shared by all signals. An `IConfiguration` is created automatically from environment variables. The -recommended method to configure the OpenTelemetry SDK is via environment variables. At a minimum, we should set -the environment variables used to configure the OTLP exporter using any suitable method for your operating system. +When calling `OpenTelemetrySdk.Create` a dedicated `IServiceCollection` and `IServiceProvider` are created for the SDK and shared by all signals. An `IConfiguration` is created automatically from environment variables. The recommended method to configure the OpenTelemetry SDK is via environment variables. At a minimum, set the environment variables used to configure the OTLP exporter using any suitable method for your operating system. ``` "OTEL_EXPORTER_OTLP_ENDPOINT" = "https://{MyServerlessEndpoint}.apm.us-east-1.aws.elastic.cloud:443", diff --git a/docs/reference/edot-sdks/dotnet/setup/console.md b/docs/reference/edot-sdks/dotnet/setup/console.md index 89658176..310e4e92 100644 --- a/docs/reference/edot-sdks/dotnet/setup/console.md +++ b/docs/reference/edot-sdks/dotnet/setup/console.md @@ -1,5 +1,6 @@ --- navigation_title: Console applications +description: Learn how to instrument console applications using the Elastic Distribution of OpenTelemetry .NET. applies_to: stack: serverless: @@ -12,14 +13,7 @@ products: # Set up EDOT .NET for console applications -Applications running without a [host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) may initialize -OpenTelemetry manually. - -:::{note} -When building console applications, consider using the features provided by -[`Microsoft.Extensions.Hosting`](https://www.nuget.org/packages/microsoft.extensions.hosting) as this enables -dependency injection and logging capabilities. -::: +You can instrument console applications using the Elastic Distribution of OpenTelemetry .NET. Applications running without a [host](https://learn.microsoft.com/dotnet/core/extensions/generic-host) can initialize OpenTelemetry manually. For example: ```csharp using OpenTelemetry; @@ -31,22 +25,19 @@ using OpenTelemetrySdk sdk = OpenTelemetrySdk.Create(builder => builder The preceding code: 1. Imports the required types from the `OpenTelemetry` namespace. -1. Creates an instance of the `OpenTelemetrySdk` using its factory `Create` method. -1. Configures the `IOpenTelemetryBuilder` by passing a lambda. -1. Enables EDOT .NET and its [opinionated defaults](edot-defaults.md) by calling `WithElasticDefaults` on the `IOpenTelemetryBuilder`. +2. Creates an instance of the `OpenTelemetrySdk` using its factory `Create` method. +3. Configures the `IOpenTelemetryBuilder` by passing a lambda. +4. Enables EDOT .NET and its [opinionated defaults](edot-defaults.md) by calling `WithElasticDefaults` on the `IOpenTelemetryBuilder`. + +When building console applications, consider using the features provided by [`Microsoft.Extensions.Hosting`](https://www.nuget.org/packages/microsoft.extensions.hosting) as this turns on dependency injection and logging capabilities. :::{warning} -The `using` keyword is applied to the `sdk` variable to define a using declaration, which ensures that the -`OpenTelemetrySdk` instance is disposed of when the application terminates. Disposing of the OpenTelemetry SDK gives the -SDK a chance to flush any telemetry held in memory. Skipping this step may result in data loss. +The `using` keyword is applied to the `sdk` variable to define a using declaration, which ensures that the `OpenTelemetrySdk` instance is disposed of when the application terminates. Disposing of the OpenTelemetry SDK gives the SDK a chance to flush any telemetry held in memory. Skipping this step may result in data loss. ::: -The above code is sufficient for many applications to achieve a reasonable out-of-the-box experience. The -`IOpenTelemetryBuilder` can be further configured as required within the target application. +The previous code is sufficient for many applications to achieve a reasonable out-of-the-box experience. The `IOpenTelemetryBuilder` can be further configured as required within the target application. -For example, we can observe an additional `ActivitySource` by chaining a call to `WithTracing`, -providing a lambda to configure the `TracerProviderBuilder` to add the name of the additional -`ActivitySource`. +For example, you can observe an additional `ActivitySource` by chaining a call to `WithTracing`, providing a lambda to configure the `TracerProviderBuilder` to add the name of the additional `ActivitySource`. ```csharp using OpenTelemetry; @@ -57,8 +48,7 @@ using OpenTelemetrySdk sdk = OpenTelemetrySdk.Create(builder => builder .WithTracing(t => t.AddSource("MyApp.SourceName"))); ``` -We can further customise the OpenTelemetry SDK with the other built-in extension methods, -such as `ConfigureResource`. +You can further customize the OpenTelemetry SDK with the other built-in extension methods, such as `ConfigureResource`. ```csharp using OpenTelemetry; @@ -71,32 +61,22 @@ using OpenTelemetrySdk sdk = OpenTelemetrySdk.Create(builder => builder .WithTracing(t => t.AddSource("MyApp.SourceName"))); ``` -## Providing configuration +## Provide configuration values -When calling `OpenTelemetrySdk.Create` a dedicated `IServiceCollection` and `IServiceProvider` will be created for the -SDK and shared by all signals. An `IConfiguration` is created automatically from environment variables. The -recommended method to configure the OpenTelemetry SDK is via environment variables. At a minimum, we should set -the environment variables used to configure the OTLP exporter using any suitable method for your operating system. +When calling `OpenTelemetrySdk.Create` a dedicated `IServiceCollection` and `IServiceProvider` is created for the SDK and shared by all signals. An `IConfiguration` is created automatically from environment variables. The recommended method to configure the OpenTelemetry SDK is via environment variables. At a minimum, set the environment variables used to configure the OTLP exporter using any suitable method for your operating system. ``` "OTEL_EXPORTER_OTLP_ENDPOINT" = "https://{MyServerlessEndpoint}.apm.us-east-1.aws.elastic.cloud:443", "OTEL_EXPORTER_OTLP_HEADERS" = "Authorization=ApiKey {MyEncodedApiKey}" ``` -:::{note} -Replace the `{MyServerlessEndpoint}` and `{MyEncodedApiKey}` placeholders above with the values provided -by your Elastic Observability backend. -::: - -### Configuring EDOT .NET +Replace the `{MyServerlessEndpoint}` and `{MyEncodedApiKey}` placeholders above with the values provided by your Elastic Observability backend. -Several configuration settings are available to control the additional features offered by EDOT .NET. -These may be configured using environment variables, `IConfiguration` and/or code-based configuration. +### Configure EDOT .NET -See the [configuration](../configuration.md) documentation for more details. +Several configuration settings are available to control the additional features offered by EDOT .NET. These might be configured using environment variables, `IConfiguration` and/or code-based configuration. Refer to [Configuration](../configuration.md) documentation for more details. -As an example, manual code-based configuration can be used to disable the instrumentation assembly scanning -feature. +As an example, manual code-based configuration can be used to disable the instrumentation assembly scanning feature. ```csharp using OpenTelemetry; @@ -117,11 +97,11 @@ using OpenTelemetrySdk sdk = OpenTelemetrySdk.Create(builder => builder The preceding code: -1. Creates an instance of `ElasticOpenTelemetryOptions` -1. Configures `SkipInstrumentationAssemblyScanning` as `true` to disable the assembly scanning feature. -1. Passes the `ElasticOpenTelemetryOptions` from the `options` variable into the `WithElasticDefaults` method. +1. Creates an instance of `ElasticOpenTelemetryOptions`. +2. Configures `SkipInstrumentationAssemblyScanning` as `true` to disable the assembly scanning feature. +3. Passes the `ElasticOpenTelemetryOptions` from the `options` variable into the `WithElasticDefaults` method. -It's also possible to use `IConfiguration` to control EDOT .NET. +You can also use `IConfiguration` to control EDOT .NET. ```csharp using OpenTelemetry; @@ -149,15 +129,15 @@ using var sdk = OpenTelemetrySdk.Create(builder => builder The preceding code: 1. Defines a constant string variable named `edotPrefix` to hold the configuration section prefix. -1. Creates a new `ConfigurationBuilder` to bind configuration values from one or more providers (sources), such as JSON. -1. Calls the `AddJsonFile` method to read configuration from a JSON file named "appsettings.json". -1. Calls the `AddInMemoryCollection` method to add configuration settings from a `Dictionary` of supplied keys and values. +2. Creates a new `ConfigurationBuilder` to bind configuration values from one or more providers (sources), such as JSON. +3. Calls the `AddJsonFile` method to read configuration from a JSON file named "appsettings.json". +4. Calls the `AddInMemoryCollection` method to add configuration settings from a `Dictionary` of supplied keys and values. 1. Adds an entry for "SkipInstrumentationAssemblyScanning" prefixed with the correct section name, setting its value to "true." - 1. Adds an entry for "LogDirectory" prefixed with the correct section name, setting its value to "C:\Logs\MyApp". -1. Builds an `IConfigurationRoot` (castable to `IConfiguration`) from the provided sources. -1. Passes the `IConfiguration` from the `config` variable into the `WithElasticDefaults` method. + 2. Adds an entry for "LogDirectory" prefixed with the correct section name, setting its value to "C:\Logs\MyApp". +5. Builds an `IConfigurationRoot` (castable to `IConfiguration`) from the provided sources. +6. Passes the `IConfiguration` from the `config` variable into the `WithElasticDefaults` method. -The example above requires the JSON configuration provider, which can be added as a NuGet package. +The previous example requires the JSON configuration provider, which you an add as a NuGet package. ```xml diff --git a/docs/reference/edot-sdks/dotnet/setup/edot-defaults.md b/docs/reference/edot-sdks/dotnet/setup/edot-defaults.md index 75abfd57..82435fb3 100644 --- a/docs/reference/edot-sdks/dotnet/setup/edot-defaults.md +++ b/docs/reference/edot-sdks/dotnet/setup/edot-defaults.md @@ -1,5 +1,6 @@ --- navigation_title: Opinionated defaults +description: When using EDOT .NET, Elastic defaults for tracing, metrics and logging are applied. These defaults are designed to provide a faster getting started experience by automatically enabling data collection from telemetry signals without requiring as much up-front code as the upstream OpenTelemetry SDK. applies_to: stack: serverless: @@ -12,11 +13,8 @@ products: # EDOT .NET opinionated defaults -When using EDOT .NET, Elastic defaults for tracing, metrics and logging are applied. These defaults are designed -to provide a faster getting started experience by automatically enabling data collection from telemetry signals without -requiring as much up-front code as the upstream OpenTelemetry SDK. This has the positive side effect of reducing the -boilerplate code you must maintain in your application. These defaults should be satisfactory for most applications -but may be overridden for advanced use cases. +When using EDOT .NET, Elastic defaults for tracing, metrics and logging are applied. These defaults are designed to provide a faster getting started experience by automatically enabling data collection from telemetry signals without requiring as much up-front code as the upstream OpenTelemetry SDK. This has the positive side effect of reducing the +boilerplate code you must maintain in your application. These defaults should be satisfactory for most applications but can be overridden for advanced use cases. ## Defaults for all signals @@ -26,28 +24,24 @@ When using any of the following registration extension methods: - `IServiceCollection.AddElasticOpenTelemetry` - `IOpenTelemetryBuilder.WithElasticDefaults` -EDOT .NET enables: +EDOT .NET turns on: -- Observation of all signals (tracing, metrics and logging) -- OTLP exporter for all signals +- Observation of all signals (tracing, metrics and logging). +- OTLP exporter for all signals. -When sending data to an Elastic Observability backend, OTLP via the EDOT Collector is recommended for -compatibility and is required for full support. EDOT .NET enables OTLP over gRPC as the default for all signals. -This behaviour can be disabled using [configuration](../configuration.md). +When sending data to an Elastic Observability backend, OTLP through the EDOT Collector is recommended for compatibility and is required for full support. EDOT .NET enables OTLP over gRPC as the default for all signals. You can turn off this behavior through [configuration](../configuration.md). -All signals are configured to apply EDOT .NET defaults for resource attributes via the `ResourceBuilder`. +All signals are configured to apply EDOT .NET defaults for resource attributes through the `ResourceBuilder`. -### Controlling defaults for each signal +### Modify defaults for each signal -For discrete control of the signals where Elastic defaults apply, consider using one of the -signal-specific extension methods for the `IOpenTelemetryBuilder`. +For discrete control of the signals where Elastic defaults apply, consider using one of the signal-specific extension methods for the `IOpenTelemetryBuilder`. - `WithElasticTracing` - `WithElasticMetrics` - `WithElasticLogging` -For example, you might choose to use the OpenTelemetry SDK but only enable tracing with Elastic -defaults using the following registration code. +For example, you might choose to use the OpenTelemetry SDK but only enable tracing with Elastic defaults using the following registration code. ```csharp using OpenTelemetry; @@ -59,8 +53,8 @@ builder.Services.AddOpenTelemetry() The preceding code: 1. Imports the required types from the `OpenTelemetry` namespace. -1. Registers the OpenTelemetry SDK for the application using `AddOpenTelemetry`. -1. Adds Elastic defaults for tracing (see below). This doesn't apply Elastic defaults for logging or metrics. +2. Registers the OpenTelemetry SDK for the application using `AddOpenTelemetry`. +3. Adds Elastic defaults for tracing (see below). This doesn't apply Elastic defaults for logging or metrics. ## Defaults for resource attributes @@ -68,12 +62,11 @@ The following attributes are added in all scenarios (NuGet and zero code install | Attribute | Details | | -------------------------- | --------------------------------------------------------------------------- | -| `service.instance.id` | Set with a random GUID to ensure runtime metrics dashboard can be filtered  | -| `telemetry.distro.name` | Set as `elastic` | -| `telemetry.distro.version` | Set as the version of the EDOT .NET | +| `service.instance.id` | Set with a random GUID to ensure runtime metrics dashboard can be filtered. | +| `telemetry.distro.name` | Set as `elastic`. | +| `telemetry.distro.version` | Set as the version of the EDOT .NET. | -When using the NuGet installation method, transistive dependencies are added for the following -contrib resource detector packages: +When using the NuGet installation method, transitive dependencies are added for the following contrib resource detector packages: - [OpenTelemetry.Resources.Host](https://www.nuget.org/packages/OpenTelemetry.Resources.Host) - [OpenTelemetry.Resources.ProcessRuntime](https://www.nuget.org/packages/OpenTelemetry.Resources.ProcessRuntime) @@ -82,8 +75,7 @@ The resource detectors are registered on the `ResourceBuilder` to enrich the res ### Instrumentation assembly scanning -Instrumentation assembly scanning checks for the presence of the following contrib resource detector packages, -automatically registering them when present. +Instrumentation assembly scanning checks for the presence of the following contrib resource detector packages, automatically registering them when present. - [OpenTelemetry.Resources.Container](https://www.nuget.org/packages/OpenTelemetry.Resources.Container) - [OpenTelemetry.Resources.OperatingSystem](https://www.nuget.org/packages/OpenTelemetry.Resources.OperatingSystem) @@ -99,40 +91,29 @@ EDOT .NET applies subtly different defaults depending on the .NET runtime versio ### HTTP traces -On .NET 9 and newer runtimes, EDOT .NET observes the `System.Net.Http` source to collect traces from the -.NET HTTP APIs. Since .NET 9, the built-in traces are compliant with current semantic conventions. Using -the built-in `System.Net.Http` source is now the recommended choice. If the target application explicitly -depends on the `OpenTelemetry.Instrumentation.Http` package, EDOT .NET assumes it should be -used instead of the built-in source. +On .NET 9 and newer runtimes, EDOT .NET observes the `System.Net.Http` source to collect traces from the .NET HTTP APIs. Since .NET 9, the built-in traces are compliant with current semantic conventions. Using the built-in `System.Net.Http` source is now the recommended choice. If the target application explicitly depends on the `OpenTelemetry.Instrumentation.Http` package, EDOT .NET assumes it should be used instead of the built-in source. :::{note} When upgrading applications to .NET 9 and newer, consider removing the package reference to `OpenTelemetry.Instrumentation.Http`. ::: -On all other runtimes, when using the NuGet installation method, a transistive dependency is included for the -[OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) -contrib instrumentation package, which is automatically registered on the `TracerProviderBuilder` via instrumentation assembly scanning. +On all other runtimes, when using the NuGet installation method, a transitive dependency is included for the [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) contrib instrumentation package, which is automatically registered on the `TracerProviderBuilder` through instrumentation assembly scanning. ### gRPC traces -When using the NuGet installation method, a transistive dependency is included for the -[OpenTelemetry.Instrumentation.GrpcNetClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.GrpcNetClient) -contrib instrumentation package. +When using the NuGet installation method, a transitive dependency is included for the [OpenTelemetry.Instrumentation.GrpcNetClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.GrpcNetClient) contrib instrumentation package. All scenarios register the gRPC client when instrumentation assembly scanning is supported and enabled. ### SQL client traces -When using the NuGet installation method, a transistive dependency is included for the -[OpenTelemetry.Instrumentation.SqlClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.SqlClient) -contrib instrumentation package. +When using the NuGet installation method, a transitive dependency is included for the [OpenTelemetry.Instrumentation.SqlClient](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.SqlClient) contrib instrumentation package. All scenarios register the SQL client when instrumentation assembly scanning is supported and enabled. ### Additional sources -EDOT .NET observes the `Elastic.Transport` source to collect traces from Elastic client libraries, such as -`Elastic.Clients.Elasticsearch`, which is built upon the [Elastic transport](https://github.com/elastic/elastic-transport-net) layer. +EDOT .NET observes the `Elastic.Transport` source to collect traces from Elastic client libraries, such as `Elastic.Clients.Elasticsearch`, which is built upon the [Elastic transport](https://github.com/elastic/elastic-transport-net) layer. ### Instrumentation assembly scanning @@ -163,14 +144,9 @@ Instrumentation assembly scanning is not supported for applications using native #### ASP.NET Core defaults -To provide a richer experience out-of-the-box, EDOT .NET registers an exception enricher for ASP.NET Core -when using instrumentation assembly scanning. +To provide a richer experience out-of-the-box, EDOT .NET registers an exception enricher for ASP.NET Core when using instrumentation assembly scanning. -When an unhandled exception occurs during a request that ASP.NET Core handles, the exception is added as -a span event using the [`AddException`](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity.addexception) -API from `System.Diagnostics`. Span events are stored as logs in the Observability backend and will appear -in the "Errors" UI. Additionally, when the `Exception.Source` property is not null, its value is added as -an attribute `exception.source` on the ASP.NET Core request span. +When an unhandled exception occurs during a request that ASP.NET Core handles, the exception is added as a span event using the [`AddException`](https://learn.microsoft.com/dotnet/api/system.diagnostics.activity.addexception) API from `System.Diagnostics`. Span events are stored as logs in the Observability backend and will appear in the Errors UI. Additionally, when the `Exception.Source` property is not null, its value is added as an attribute `exception.source` on the ASP.NET Core request span. ## Defaults for metrics @@ -178,43 +154,31 @@ EDOT .NET applies subtly different defaults depending on the .NET runtime versio ### HTTP metrics -On .NET 9 and newer runtimes, EDOT .NET observes the `System.Net.Http` meter to collect metrics from the -.NET HTTP APIs. Since .NET 9, the built-in metrics are compliant with current semantic conventions. Using -the built-in `System.Net.Http` meter is therefore recommended. +On .NET 9 and newer runtimes, EDOT .NET observes the `System.Net.Http` meter to collect metrics from the .NET HTTP APIs. Since .NET 9, the built-in metrics are compliant with current semantic conventions. Using the built-in `System.Net.Http` meter is therefore recommended. -If the target application has an explicit dependency on the `OpenTelemetry.Instrumentation.Http` package, -EDOT .NET assumes that it should be used instead of the built-in meter. +If the target application has an explicit dependency on the `OpenTelemetry.Instrumentation.Http` package, EDOT .NET assumes that it should be used instead of the built-in meter. :::{note} When upgrading applications to .NET 9 and newer, consider removing the package reference to `OpenTelemetry.Instrumentation.Http`. ::: -On all other runtimes, when using the NuGet installation method, a transistive dependency is included for the -[OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) -contrib instrumentation package, which is registered on the `MeterProviderBuilder` via instrumentation assembly scanning. +On all other runtimes, when using the NuGet installation method, a transitive dependency is included for the [OpenTelemetry.Instrumentation.Http](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Http) contrib instrumentation package, which is registered on the `MeterProviderBuilder` via instrumentation assembly scanning. ### Runtime metrics -On .NET 9 and newer runtimes, EDOT .NET observes the `System.Runtime` meter to collect metrics from the -.NET HTTP APIs. Since .NET 9, the built-in traces are compliant with current semantic conventions. Using -the built-in `System.Runtime` meter is therefore recommended. +On .NET 9 and newer runtimes, EDOT .NET observes the `System.Runtime` meter to collect metrics from the .NET HTTP APIs. Since .NET 9, the built-in traces are compliant with current semantic conventions. Using the built-in `System.Runtime` meter is therefore recommended. -If the target application has an explicit dependency on the `OpenTelemetry.Instrumentation.Runtime` package, -EDOT .NET assumes that it should be used instead of the built-in meter. +If the target application has an explicit dependency on the `OpenTelemetry.Instrumentation.Runtime` package, EDOT .NET assumes that it should be used instead of the built-in meter. :::{note} When upgrading applications to .NET 9 and newer, consider removing the package reference to `OpenTelemetry.Instrumentation.Runtime`. ::: -On all other runtimes, when using the NuGet installation method, a transistive dependency is included for the -[OpenTelemetry.Instrumentation.Runtime](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Runtime) -contrib instrumentation package, which is registered on the `MeterProviderBuilder` via instrumentation assembly scanning. +On all other runtimes, when using the NuGet installation method, a transitive dependency is included for the [OpenTelemetry.Instrumentation.Runtime](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Runtime) contrib instrumentation package, which is registered on the `MeterProviderBuilder` via instrumentation assembly scanning. ### Process metrics -When using the NuGet installation method, a transistive dependency is included for the -[OpenTelemetry.Instrumentation.Process](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Process) -contrib instrumentation package. Process metrics are observed in all scenarios. +When using the NuGet installation method, a transitive dependency is included for the [OpenTelemetry.Instrumentation.Process](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.Process) contrib instrumentation package. Process metrics are observed in all scenarios. ### ASP.NET Core metrics @@ -235,8 +199,7 @@ EDOT .NET observes the `System.Net.NameResolution` meter, to collect metrics fro ### Instrumentation assembly scanning -Instrumentation assembly scanning checks for the presence of the following contrib instrumentation packages, -registering them when present. +Instrumentation assembly scanning checks for the presence of the following contrib instrumentation packages, registering them when present. - [OpenTelemetry.Instrumentation.AspNet](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNet) - [OpenTelemetry.Instrumentation.AspNetCore](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore) @@ -255,39 +218,28 @@ Instrumentation assembly scanning is not supported for applications using native ### Configuration defaults -To ensure the best compatibility of metric data (specifically from the histogram instrument), EDOT .NET -defaults the `TemporalityPreference` configuration setting on `MetricReaderOptions` to use the -`MetricReaderTemporalityPreference.Delta` temporality. +To ensure the best compatibility of metric data (specifically from the histogram instrument), EDOT .NET defaults the `TemporalityPreference` configuration setting on `MetricReaderOptions` to use the `MetricReaderTemporalityPreference.Delta` temporality. ## Defaults for logging -EDOT .NET enables the following options that are not enabled by default when using the upstream -OpenTelemetry SDK. +EDOT .NET enables the following options that are not enabled by default when using the upstream OpenTelemetry SDK. | Option | EDOT .NET default | OpenTelemetry SDK default | | ------------------------ | ----------------- | ------------------------- | | IncludeFormattedMessage | `true` | `false` | -| IncludeScopes | `false` (Since 1.0.2) * | `false` | +| IncludeScopes | `false` (Since 1.0.2) | `false` | -\* Since 1.0.2 `IncludeScopes` is no longer enabled by default. See [troubleshooting](../troubleshooting.md#missing-log-records). -1.0.0 and 1.0.1 default to `true`. +Since 1.0.2 `IncludeScopes` is no longer enabled by default. Refer to [Troubleshooting](../troubleshooting.md#missing-log-records). 1.0.0 and 1.0.1 default to `true`. ### Instrumentation assembly scanning -Instrumentation assembly scanning is enabled by default and is designed to simplify the registration -code required to configure the OpenTelemetry SDK. Instrumentation assembly scanning uses reflection -to invoke the required registration method for the contrib instrumentation and resource detector packages. +Instrumentation assembly scanning is enabled by default and is designed to simplify the registration code required to configure the OpenTelemetry SDK. Instrumentation assembly scanning uses reflection to invoke the required registration method for the contrib instrumentation and resource detector packages. :::{warning} -It may not be safe to manually call the `AddXyzInstrumentation` method in combination with assembly scanning, -for all instrumentations. When using EDOT .NET, we strongly recommend you remove the registration of instrumentation -to avoid overhead and mitigate the potential for duplicated spans. This has a positive side-effect of simplifying the -code you need to manage. +Calling the `AddXyzInstrumentation` method in combination with assembly scanning, might not be safe for all instrumentations. When using EDOT .NET, remove the registration of instrumentation to avoid overhead and mitigate the potential for duplicated spans. This has a positive side-effect of simplifying the code you need to manage. ::: -Alternatively, if you need to configure advanced options when registering instrumentation, -disable instrumentation assembly scanning via [configuration](../configuration.md) and prefer manually registering -all instrumentation in your application code. +If you need to configure advanced options when registering instrumentation, turn off instrumentation assembly scanning through [Configuration](../configuration.md) and prefer manually registering all instrumentation in your application code. :::{warning} Instrumentation assembly scanning is not supported for applications using native [AOT](https://learn.microsoft.com/dotnet/core/deploying/native-aot) compilation. diff --git a/docs/reference/edot-sdks/dotnet/setup/index.md b/docs/reference/edot-sdks/dotnet/setup/index.md index 1bf725db..4af94100 100644 --- a/docs/reference/edot-sdks/dotnet/setup/index.md +++ b/docs/reference/edot-sdks/dotnet/setup/index.md @@ -1,5 +1,6 @@ --- navigation_title: Setup +description: Learn how to set up and configure the Elastic Distribution of OpenTelemetry .NET to instrument your application or service. applies_to: stack: serverless: @@ -10,20 +11,17 @@ products: - id: edot-dotnet --- -# Setting up the EDOT .NET SDK +# Set up the EDOT .NET SDK + +Learn how to set up and configure the Elastic Distribution of OpenTelemetry .NET to instrument your application or service. ## Quickstart guide -EDOT .NET is designed to be straightforward to integrate into your applications. Integration includes applications that have previously used the -[OpenTelemetry SDK](https://opentelemetry.io/docs/languages/net/), those that are transitioning from the -[Elastic APM Agent](https://www.elastic.co/guide/en/apm/agent/dotnet/current/index.html) and those introducing observability instrumentation for -the first time. When the OpenTelemetry SDK or Elastic APM Agent are already in use, minor code changes are required at the point of registration. -See the [migration](../migration.md) documentation for more details. +EDOT .NET is designed to be straightforward to integrate into your applications. Integration includes applications that have previously used the [OpenTelemetry SDK](https://opentelemetry.io/docs/languages/net/), those that are transitioning from the [Elastic APM Agent](https://www.elastic.co/guide/en/apm/agent/dotnet/current/index.html) and those introducing observability instrumentation for the first time. When the OpenTelemetry SDK or Elastic APM Agent are already in use, minor code changes are required at the point of registration. Refer to [Migration](../migration.md) for more details. This quickstart guide documents the introductory steps required to set up OpenTelemetry using EDOT .NET for an ASP.NET Core [minimal API](https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis) application. For detailed, technology-specific steps, see: -* ASP.NET Core * [ASP.NET (.NET Framework)](./aspnet.md) * [Console applications](./console.md) * [Worker services](./worker-services.md) @@ -33,30 +31,12 @@ This quickstart guide documents the introductory steps required to set up OpenTe Before getting started: -* **Check your .NET SDK version**. The current documentation and examples are written with .NET 8 and newer applications in mind. -Before continuing, install a locally supported [.NET SDK version](https://dotnet.microsoft.com/en-us/download/dotnet). -* **Create a new ASP.NET Core minimal API project**. You'll need an application to the instrument with OpenTelemetry. This quickstart guide uses -an ASP.NET Core minimal API project. You can follow along with a new or existing ASP.NET Core application. See the -technology-specific documentation for guidance with specific .NET application templates. -* **Set up Elastic Observability**. You'll need somewhere to send the gathered OpenTelemetry data so that it can be viewed and analyzed. -This documentation assumes you're using [Elastic Cloud](https://www.elastic.co/cloud) with an [Elastic Observability](https://www.elastic.co/observability) -hosted deployment or serverless project. You can use an existing one or set up a new one. - -To create your first Elastic Observability serverless project: - -1. Sign up for a [free Elastic Cloud trial](https://cloud.elastic.co/registration) or sign into an existing account. -1. Go to . -1. Click **Create serverless project**. -1. Choose **Elastic for Observability**. -1. Provide a name for your serverless project and click **Create serverless project**. -1. Once the project is ready, click *Open* to access Kibana -1. Choose **Add data** to take you to the onboarding home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.{CLOUDPROVIDER}.elastic.cloud/app/observabilityOnboarding`). -1. Choose **Application** and select **OpenTelemetry** -1. From step 2, select **Managed OTLP Endpoint** -1. Follow the onboarding instructions in step 3 to create an API key and capture the endpoint URL that will be used when configuring application(s) using environment variables. - -:::{warning} -When using Serverless, you must use the Managed OTLP Endpoint URL (tech preview) for the best (and supported) experience when using EDOT .NET. +* Check your .NET SDK version. Before continuing, install a locally supported [.NET SDK version](https://dotnet.microsoft.com/en-us/download/dotnet). +* Create a new ASP.NET Core minimal API project. You need an application to instrument with OpenTelemetry. This quickstart guide uses an ASP.NET Core minimal API project. You can follow along with a new or existing ASP.NET Core application. Refer to the technology-specific documentation for guidance with specific .NET application templates. +* Set up Elastic Observability. You need somewhere to send the gathered OpenTelemetry data so that it can be viewed and analyzed. This documentation assumes you're using [Elastic Cloud](https://www.elastic.co/cloud) with an [Elastic Observability](https://www.elastic.co/observability) hosted deployment or serverless project. You can use an existing one or set up a new one. + +:::{tip} +When using Serverless, use the Managed OTLP Endpoint UR for the best experience when using EDOT .NET. ::: ### Installing the NuGet packages @@ -72,14 +52,12 @@ reference to your project file: Replace the `` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/Elastic.OpenTelemetry). ::: -EDOT .NET includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the OpenTelemetry SDK package to your project directly. However, -you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. +EDOT .NET includes a transitive dependency on the OpenTelemetry SDK, so you do not need to add the OpenTelemetry SDK package to your project directly. However, +you can explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. #### ASP.NET Core instrumentation -To observe and capture the built-in ASP.NET Core instrumentation, the OpenTelemetry instrumentation for [ASP.NET Core -NuGet](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore) package is required. Due to its dependencies, this -package is not automatically available when adding `Elastic.OpenTelemetry` to your project. +To observe and capture the built-in ASP.NET Core instrumentation, the OpenTelemetry instrumentation for [ASP.NET Core NuGet](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore) package is required. Due to its dependencies, this package is not automatically available when adding `Elastic.OpenTelemetry` to your project. Manually add the latest version to your project file: @@ -91,35 +69,26 @@ Manually add the latest version to your project file: Replace the `` version placeholder with the [latest available package from NuGet.org](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore). ::: -The presence of this package is detected by the EDOT instrumentation assembly scanning feature (enabled by default). +The presence of this package is detected by the EDOT instrumentation assembly scanning feature (turned on by default). ### Registering OpenTelemetry with EDOT .NET -To register the OpenTelemetry SDK via EDOT .NET, the recommended approach is to use the extension method available on -`IHostApplicationBuilder`. `IHostApplicationBuilder` is the abstraction representing the .NET generic host responsible -for managing application startup and lifetime in ASP.NET Core. +To register the OpenTelemetry SDK via EDOT .NET, the recommended approach is to use the extension method available on `IHostApplicationBuilder`. `IHostApplicationBuilder` is the abstraction representing the .NET generic host responsible for managing application startup and lifetime in ASP.NET Core. ```csharp var builder = WebApplication.CreateBuilder(args); builder.AddElasticOpenTelemetry(); ``` -Immediately after creating the WebApplicationBuilder, which implements `IHostApplicationBuilder`, call the -`AddElasticOpenTelemetry` method. `AddElasticOpenTelemetry` registers the OpenTelemetry SDK for .NET, applying the Elastic -[opiniated defaults](./edot-defaults.md). The Elastic defaults enable tracing, metrics, log signals, and the OTLP exporter. -Additionally, the EDOT performs automatic instrumentation assembly scanning to enable the ASP.NET Core instrumentation -that we added in the previous step. With the upstream "vanilla" SDK, additional lines of code would be required to register -the instrumentation. EDOT .NET aims to simplify the experience of getting started. +Immediately after creating the WebApplicationBuilder, which implements `IHostApplicationBuilder`, call the `AddElasticOpenTelemetry` method. `AddElasticOpenTelemetry` registers the OpenTelemetry SDK for .NET, applying the Elastic [opinionated defaults](./edot-defaults.md). The Elastic defaults enable tracing, metrics, log signals, and the OTLP exporter. + +Additionally, EDOT performs automatic instrumentation assembly scanning to enable the ASP.NET Core instrumentation that we added in the previous step. With the upstream SDK, additional lines of code would be required to register the instrumentation. EDOT .NET aims to simplify the experience of getting started. -### Configuring the OpenTelemetry resource attributes +### Configure the OpenTelemetry resource attributes -When exporting telemetry data from an application, resource attributes are used to represent metadata about the entity -producing the telemetry. While defaults are applied for required attributes such as `service.name`, it is recommended to -explicitly set a descriptive service name to distinguish its data in the Elastic Observability UI. +When exporting telemetry data from an application, resource attributes are used to represent metadata about the entity producing the telemetry. While defaults are applied for required attributes such as `service.name`. Explicitly set a descriptive service name to distinguish its data in the Elastic Observability UI. -The OpenTelemetry SDK supports several mechanisms to configure resource attributes. For simple scenarios, the service -information can be set programmatically. To achieve this when using EDOT, the `AddElasticOpenTelemetry` method includes an -overload accepting an `Action` used to configure the OpenTelemetry SDK via its builder API. +The OpenTelemetry SDK supports several mechanisms to configure resource attributes. For simple scenarios, the service information can be set programmatically. To achieve this when using EDOT, the `AddElasticOpenTelemetry` method includes an overload accepting an `Action` used to configure the OpenTelemetry SDK through its builder API. To specify a service name, we can amend the preceding code as follows: @@ -135,14 +104,9 @@ using OpenTelemetry; using OpenTelemetry.Resources; ``` -Alternatively, the `OTEL_SERVICE_NAME` environment variable can be used to configure the service name. -There are two ways to specify this with the OpenTelemetry SDK. Either, as a traditional environment variable, configured before -launching the process, or as an entry in the [.NET configuration APIs](https://learn.microsoft.com/dotnet/core/extensions/configuration). -These APIs are available and used by default in generic host applications such as ASP.NET Core. +Alternatively, the `OTEL_SERVICE_NAME` environment variable can be used to configure the service name. There are two ways to specify this with the OpenTelemetry SDK. Either, as a traditional environment variable, configured before launching the process, or as an entry in the [.NET configuration APIs](https://learn.microsoft.com/dotnet/core/extensions/configuration). These APIs are available and used by default in generic host applications such as ASP.NET Core. -To use `IConfiguration` to specify the service name, create an entry for the key `OTEL_SERVICE_NAME`, with the value representing -your preferred service name. Configuring this entry can be achieved through any of the available .NET configuration providers, for example, -by creating a configuration entry in the `appsettings.json` file: +To use `IConfiguration` to specify the service name, create an entry for the key `OTEL_SERVICE_NAME`, with the value representing your preferred service name. Configuring this entry can be achieved through any of the available .NET configuration providers, for example, by creating a configuration entry in the `appsettings.json` file: ```json { @@ -157,37 +121,26 @@ by creating a configuration entry in the `appsettings.json` file: } ``` -OpenTelemetry configuration environment variables should be specified as a top-level key/value pair as with the `OTEL_SERVICE_NAME` in -the preceding code snippet. +OpenTelemetry configuration environment variables should be specified as a top-level key/value pair as with the `OTEL_SERVICE_NAME` in the preceding code snippet. -### Configuring the OTLP endpoint +### Configure the OTLP endpoint -The configuration documented so far ensures that when the application starts, the OpenTelemetry SDK is launched with the -[EDOT .NET defaults](./edot-defaults.md), enabling all signals and export via OTLP. Unless configured otherwise, the OTLP exporter in the SDK defaults to -sending data to `localhost` on the well-known port for OTLP over gRPC, 4317. If you are running a local collector, this may be -sufficient, but in most cases, you will need to configure the correct endpoint for exporting telemetry data. +The configuration documented so far ensures that when the application starts, the OpenTelemetry SDK is launched with the [EDOT .NET defaults](./edot-defaults.md), activating all signals and exporting telemetry through OTLP. Unless configured otherwise, the OTLP exporter in the SDK defaults to sending data to `localhost` on the default port for OTLP over gRPC, 4317. If you are running a local collector, this might be sufficient, but in most cases you will need to configure the correct endpoint for exporting telemetry data. -In this quickstart guide, we assume the use of Elastic Cloud Serverless as the backend. In the prerequisites, the essential steps -to create a project were documented. The onboarding "Add data" page provides the environment variables required to send telemetry data to the Elastic -Observability backend. This information includes the endpoint URL and API key that should be used when exporting data. The -application must be configured to use the endpoint and authorization header when exporting telemetry data. +In this quickstart guide, Elastic Cloud Serverless is the backend. The onboarding **Add data** page of Elastic Observability provides the environment variables required to send telemetry data to the Elastic Observability backend. This information includes the endpoint URL and API key that should be used when exporting data. The application must be configured to use the endpoint and authorization header when exporting telemetry data. -As with most OpenTelemetry configuration, this can be achieved by setting the required environment variables, including providing them via application -configuration. The values (particularly the API key) are sensitive and should be secured. We can leverage the -[Secret Manager](https://learn.microsoft.com/aspnet/core/security/app-secrets) feature during local development. Once enabled +As with most OpenTelemetry configuration, you can also configure the endpoint through environment variables, including providing them through application configuration. The values are sensitive and should be secured. Use the [Secret Manager](https://learn.microsoft.com/aspnet/core/security/app-secrets) feature during local development. Once enabled for your application, add `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` as keys with their respective values. -:::{tip} Recommendation +:::{tip} Strongly consider using a key/secret store for production environments. ::: -### Instrumenting application code +### Instrument application code -EDOT .NET enables the collection of trace, metric and log signals by default. With no additional configuration, your configured Elastic -Observability backend will receive telemetry data from your application at runtime. Development teams are encouraged to enrich the value -of telemetry by instrumenting their code to emit application-specific telemetry data such as traces, metrics and logs. +EDOT .NET enables the collection of trace, metric, and log signals by default. With no additional configuration, your configured Elastic Observability backend will receive telemetry data from your application at runtime. Development teams are encouraged to enrich the value of telemetry by instrumenting their code to emit application-specific telemetry data such as traces, metrics, and logs. -In .NET, it is recommended that the built-in .NET APIs be used for this instrumentation. See: +In .NET, use the built-in .NET APIs for each signal: - [Logs](https://learn.microsoft.com/dotnet/core/extensions/logging) - [Traces](https://learn.microsoft.com/dotnet/core/diagnostics/distributed-tracing-instrumentation-walkthroughs) @@ -195,6 +148,4 @@ In .NET, it is recommended that the built-in .NET APIs be used for this instrume ### Next steps -Visit the technology-specific documentation pages for further details on using EDOT .NET in those application types. -The [OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/net/getting-started/) provides more examples of -working with the .NET SDK. \ No newline at end of file +Refer to the technology-specific documentation pages for further details on using EDOT .NET in those application types. The [OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/net/getting-started/) provides more examples of working with the .NET SDK. \ No newline at end of file diff --git a/docs/reference/edot-sdks/dotnet/setup/worker-services.md b/docs/reference/edot-sdks/dotnet/setup/worker-services.md index dd1bfc56..1021afcc 100644 --- a/docs/reference/edot-sdks/dotnet/setup/worker-services.md +++ b/docs/reference/edot-sdks/dotnet/setup/worker-services.md @@ -1,5 +1,6 @@ --- navigation_title: .NET worker services +description: Learn how to instrument .NET worker services for Elastic Observability using the Elastic Distribution of OpenTelemetry .NET. applies_to: stack: serverless: @@ -12,9 +13,7 @@ products: # Set up EDOT .NET for worker services -When building long-running [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers) -using the Worker Service template, OpenTelemetry is introduced using the same approach as for ASP.NET Core. -The recommended way to enable EDOT .NET is by calling `AddElasticOpenTelemetry` on the `HostApplicationBuilder`. +When building long-running [worker services](https://learn.microsoft.com/en-us/dotnet/core/extensions/workers) using the Worker Service template, OpenTelemetry is introduced using the same approach as for ASP.NET Core. The recommended way to turn on EDOT .NET is by calling `AddElasticOpenTelemetry` on the `HostApplicationBuilder`. ```csharp using Example.WorkerService; @@ -29,34 +28,25 @@ var host = builder.Build(); host.Run(); ``` -The preceding code: +The previous code: 1. Creates a `HostApplicationBuilder` using the `Host.CreateApplicationBuilder` factory method. -1. Enables EDOT .NET by calling `AddElasticOpenTelemetry` on the `HostApplicationBuilder`. -1. Registers application-specific types into the `IServiceCollection` (see below). -1. Builds and runs the `IHost` to execute the application workload. +2. Turns on EDOT .NET by calling `AddElasticOpenTelemetry` on the `HostApplicationBuilder`. +3. Registers application-specific types into the `IServiceCollection`. +4. Builds and runs the `IHost` to execute the application workload. -Because the worker service template is based on the generic host, shared with ASP.NET Core applications, -this is the same approach as shown in the [getting started](index.md) and ASP.NET Core examples -and the same techniques for configuration and usage apply. +Because the worker service template is based on the generic host, shared with ASP.NET Core applications, this is the same approach as shown in the [getting started](index.md) and the same techniques for configuration and usage apply. -## Instrumenting worker services +## Instrument worker services -Next, we will explore a more complete example, focusing on how instrumentation can be added and -observed for a basic worker service. We will instrument an application designed to -read and process messages from a queue (simulated for simplicity). - -In the preceding code, two application types were registered into the dependency injection container that -we haven't yet discussed. +Consider an application designed to read and process messages from a queue (simulated for simplicity). In the preceding code, two application types were registered into the dependency injection container: ```csharp builder.Services.AddSingleton(); builder.Services.AddHostedService(); ``` -`QueueReader` is a class that abstracts the reading of messages from a queue. This example simulates -this by returning a message every five seconds. In practice, an actual application would receive messages from a -source such as AWS SQS or Azure Service Bus. +`QueueReader` is a class that abstracts the reading of messages from a queue. This example simulates this by returning a message every five seconds. In practice, an actual application would receive messages from a source such as AWS SQS or Azure Service Bus. ```csharp using System.Runtime.CompilerServices; @@ -76,11 +66,11 @@ public class QueueReader } ``` -The preceding code: +The previous code: 1. Defines a `GetMessages` method, returning an `IAsyncEnumerable`. -1. The while loop continues until it is cancelled. -1. It simulates receiving a message from a queue, in this case, yielding one every five seconds. +2. The while loop continues until it is cancelled. +3. It simulates receiving a message from a queue, in this case, yielding one every five seconds. For this example, the `Message` type is a simple record class exposing an `Id` property. @@ -129,13 +119,13 @@ public class Worker : BackgroundService } ``` -The preceding code: +The previous code: 1. Accepts an `ILogger` and `QueueReader` in the constructor, provided by dependency injection. -1. Implements a long-running work loop in `ExecuteAsync`. -1. Within the loop, it waits for a message to be made available by the `QueueReader` before processing it. -1. `ProcessMessageAsync` provides a dummy processing implementation which fails occasionally. -1. The code is currently instrumented with logging, recording an error for messages it fails to process. +2. Implements a long-running work loop in `ExecuteAsync`. +3. Within the loop, it waits for a message to be made available by the `QueueReader` before processing it. +4. `ProcessMessageAsync` provides a dummy processing implementation which fails occasionally. +5. The code is currently instrumented with logging, recording an error for messages it fails to process. In the remaining part of this example, we'll introduce tracing and metrics instrumentation for this application. @@ -157,22 +147,20 @@ using System.Diagnostics; using System.Diagnostics.Metrics; ``` -The preceding code: +The previous code: 1. Adds the 'DiagnosticName' field to define a unique name used for this application's telemetry signals that we'll later use to observe them. -1. Creates a static `ActivitySource`, which will be the source for `Activity` instances used for trace +2. Creates a static `ActivitySource`, which will be the source for `Activity` instances used for trace instrumentation. It uses the name defined in the 'DiagnosticName' constant field. -1. Creates a static `Meter`, which will be the source for metrics. It also uses the name defined in the +3. Creates a static `Meter`, which will be the source for metrics. It also uses the name defined in the 'DiagnosticName' constant field. -1. Creates a `Counter` stored in the field 'MessagesReadCounter'. This instrument has the name +4. Creates a `Counter` stored in the field 'MessagesReadCounter'. This instrument has the name 'elastic.processor.messages_read'. -The naming of custom metrics is a decision left to organizations. As a good practice, the name is prefixed -with a unique identifier for the metric owner and uses dot notation to provide a concise yet meaningful name. +The naming of custom metrics is a decision left to organizations. As a good practice, the name is prefixed with a unique identifier for the metric owner and uses dot notation to provide a concise yet meaningful name. -The final step is to record telemetry when processing messages. We'll amend the `ExecuteAsync` method to add -instrumentation. +The final step is to record telemetry when processing messages. We'll amend the `ExecuteAsync` method to add instrumentation. ```csharp protected override async Task ExecuteAsync(CancellationToken stoppingToken) @@ -197,18 +185,14 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken) } ``` -The preceding code: +The previous code: -1. Starts an `Activity` using `ActivitySource.StartActivity`. As a reminder, an activity in .NET -is a "span" in OpenTelemetry terminology. The activity is given a name and optionally an `ActivityKind`. -1. The message ID is added as a tag (attribute in OpenTelemetry parlance) using the `SetTag` method. It's -important to note the null conditional operator `activity?` is used when calling methods on the `Activity` -which may be null if unobserved. -1. The code also increments the counter stored in the 'MessagesReadCounter' field. -1. After processing the message, if processing fails, we use `SetStatus` to identify that there was an error. +1. Starts an `Activity` using `ActivitySource.StartActivity`. As a reminder, an activity in .NET is a "span" in OpenTelemetry terminology. The activity is given a name and optionally an `ActivityKind`. +2. The message ID is added as a tag (attribute in OpenTelemetry parlance) using the `SetTag` method. The null conditional operator `activity?` is used when calling methods on the `Activity`, which might be null if unobserved. +3. The code also increments the counter stored in the 'MessagesReadCounter' field. +4. After processing the message, if processing fails, we use `SetStatus` to identify that there was an error. -With the instrumentation in place, we need to make a final change to our 'Program.cs' file to configure -OpenTelemetry to observe our new instrumentation. +With the instrumentation in place, we need to make a final change to our 'Program.cs' file to configure OpenTelemetry to observe our new instrumentation. ```csharp builder.AddElasticOpenTelemetry(b => b @@ -216,14 +200,9 @@ builder.AddElasticOpenTelemetry(b => b .WithMetrics(m => m.AddMeter(Worker.DiagnosticName))); ``` -The preceding code: +The previous code: -1. Configures tracing using `WithTracing` to add the diagnostic name as a source for trace telemetry -we wish to collect and export. The `AddSource` method is called on the builder to configure this. -1. Configures metrics using `WithMetrics` to add the diagnostic name as a meter for metrics telemetry -we wish to collect and export. The `AddMeter` method is called on the builder to configure this. +1. Configures tracing using `WithTracing` to add the diagnostic name as a source for trace telemetry we wish to collect and export. The `AddSource` method is called on the builder to configure this. +2. Configures metrics using `WithMetrics` to add the diagnostic name as a meter for metrics telemetry we wish to collect and export. The `AddMeter` method is called on the builder to configure this. -With these changes in place, this sample application is now instrumented, and for each message processed, a -span will be created and exported. We also increment a metric for which the value will be periodically sent. -EDOT .NET configures the delta temporality [by default](../setup/edot-defaults.md), so each exported value for -the counter will be the count since the last export. \ No newline at end of file +With these changes in place, this sample application is now instrumented, and for each message processed, a span will be created and exported. We also increment a metric for which the value will be periodically sent. EDOT .NET configures the delta temporality [by default](../setup/edot-defaults.md), so each exported value for the counter will be the count since the last export. \ No newline at end of file diff --git a/docs/reference/edot-sdks/dotnet/setup/zero-code.md b/docs/reference/edot-sdks/dotnet/setup/zero-code.md index 0faa226f..dd96ecfc 100644 --- a/docs/reference/edot-sdks/dotnet/setup/zero-code.md +++ b/docs/reference/edot-sdks/dotnet/setup/zero-code.md @@ -1,5 +1,6 @@ --- navigation_title: Zero-code instrumentation +description: Use the EDOT .NET automatic instrumentation to send traces and metrics from .NET applications and services to observability backends without having to modify source code. applies_to: stack: serverless: @@ -12,17 +13,13 @@ products: # Using profiler-based zero-code instrumentation -EDOT .NET includes a redistribution of the zero-code installer scripts so most of the documentation -in the upstream [.NET zero-code instrumentation documentation](https://opentelemetry.io/docs/zero-code/dotnet/) applies. +EDOT .NET includes a redistribution of the zero-code installer scripts so most of the documentation in the upstream [.NET zero-code instrumentation documentation](https://opentelemetry.io/docs/zero-code/dotnet/) applies. -Use the EDOT .NET automatic instrumentation to send traces and metrics from .NET applications and services to observability -backends without having to modify source code. +Use the EDOT .NET automatic instrumentation to send traces and metrics from .NET applications and services to observability backends without having to modify source code. ## Compatibility -EDOT .NET automatic instrumentation should work with all officially supported operating systems and versions of .NET. - -The minimal supported version of .NET Framework is 4.6.2. +EDOT .NET automatic instrumentation should work with all officially supported operating systems and versions of .NET. The minimal supported version of .NET Framework is 4.6.2. Supported processor architectures are: @@ -92,4 +89,4 @@ Get-Command -Module OpenTelemetry.DotNet.Auto Get-Help Install-OpenTelemetryCore -Detailed ``` -For more information on instrumenting specific applicatin types visit the [upstream OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/dotnet/). \ No newline at end of file +For more information on instrumenting specific application types visit the [upstream OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/dotnet/). \ No newline at end of file diff --git a/docs/reference/edot-sdks/dotnet/supported-technologies.md b/docs/reference/edot-sdks/dotnet/supported-technologies.md index 41221303..a98ee1df 100644 --- a/docs/reference/edot-sdks/dotnet/supported-technologies.md +++ b/docs/reference/edot-sdks/dotnet/supported-technologies.md @@ -1,5 +1,6 @@ --- -navigation_title: Supported Technologies +navigation_title: Supported technologies +description: Technologies supported by the Elastic Distribution of OpenTelemetry .NET. applies_to: stack: serverless: diff --git a/docs/reference/edot-sdks/dotnet/troubleshooting.md b/docs/reference/edot-sdks/dotnet/troubleshooting.md index 2ea491d9..81130bcb 100644 --- a/docs/reference/edot-sdks/dotnet/troubleshooting.md +++ b/docs/reference/edot-sdks/dotnet/troubleshooting.md @@ -1,5 +1,6 @@ --- navigation_title: Troubleshooting +description: Use the information in this section to troubleshoot common problems affecting the Elastic Distribution of OpenTelemetry .NET. applies_to: stack: serverless: diff --git a/docs/reference/edot-sdks/java/configuration.md b/docs/reference/edot-sdks/java/configuration.md index 58c210c6..40663a36 100644 --- a/docs/reference/edot-sdks/java/configuration.md +++ b/docs/reference/edot-sdks/java/configuration.md @@ -11,7 +11,7 @@ products: - id: edot-java --- -# Configuring the EDOT Java Agent +# Configure the EDOT Java agent The [minimal configuration](#minimal-configuration) section provides a recommended starting point for EDOT Java configuration. diff --git a/docs/reference/edot-sdks/java/features.md b/docs/reference/edot-sdks/java/features.md index 29276266..5a0ef7ae 100644 --- a/docs/reference/edot-sdks/java/features.md +++ b/docs/reference/edot-sdks/java/features.md @@ -13,62 +13,49 @@ products: # Features of the EDOT Java Agent -The EDOT Java agent is a [distribution](https://opentelemetry.io/docs/concepts/distributions/) of -[OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) agent, it thus -inherits all the features of the OpenTelemetry Java Instrumentation to capture logs, metrics and traces. +The EDOT Java agent is a [distribution](https://opentelemetry.io/docs/concepts/distributions/) of [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) agent. It inherits all the features of the OpenTelemetry Java Instrumentation to capture logs, metrics, and traces. The EDOT Java agent also provides: -- exclusive features that are _not available_ in the [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) -- features of [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) with [different default configuration](./configuration.md#configuration-options) +- Exclusive features that are not available in the [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation). +- Features of [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) with [different default configuration](./configuration.md#configuration-options). -In addition to the features listed here, see [supported technologies](./supported-technologies.md) for an overview of the supported technologies. +In addition to the features listed, refer to [Supported technologies](./supported-technologies.md). ## Resource attributes -The EDOT Java agent includes the following resource attributes providers from [opentelemetry-java-contrib](https://github.com/open-telemetry/opentelemetry-java-contrib/) -- AWS: [aws-resources](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/aws-resources) (_enabled_ by default) -- GCP: [gcp-resources](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-resources) (_enabled_ by default) -- application server service name detection: [resource-providers](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/resource-providers) +The EDOT Java agent includes the following resource attributes providers from [opentelemetry-java-contrib](https://github.com/open-telemetry/opentelemetry-java-contrib/): -## Inferred spans - -The EDOT Java agent includes the [Inferred Spans Extension](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/inferred-spans) -from [opentelemetry-java-contrib](https://github.com/open-telemetry/opentelemetry-java-contrib/). +- AWS: [aws-resources](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/aws-resources). Turned on by default. +- GCP: [gcp-resources](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-resources). Turned on by default. +- Application server service name detection: [resource-providers](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/resource-providers). -This extension provides the ability to enhance the traces by creating spans from [async-profiler](https://github.com/async-profiler/async-profiler) data without the need of explicit instrumentation of corresponding spans. +## Inferred spans -This feature is disabled by default and can be enabled by setting `OTEL_INFERRED_SPANS_ENABLED` to `true`. +The EDOT Java agent includes the [Inferred Spans Extension](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/inferred-spans) from [opentelemetry-java-contrib](https://github.com/open-telemetry/opentelemetry-java-contrib/). This extension provides the ability to enhance the traces by creating spans from [async-profiler](https://github.com/async-profiler/async-profiler) data without the need of explicit instrumentation of corresponding spans. -See [inferred-spans](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/inferred-spans) documentation for configuration options. +This feature is turned off by default and can be activated by setting `OTEL_INFERRED_SPANS_ENABLED` to `true`. Refer to [Inferred-spans](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/inferred-spans) documentation for configuration options. ## Span stacktrace -The EDOT Java agent includes the [Span Stacktrace Extension](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/span-stacktrace) -from [opentelemetry-java-contrib](https://github.com/open-telemetry/opentelemetry-java-contrib/). +The EDOT Java agent includes the [Span Stacktrace Extension](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/span-stacktrace) from [opentelemetry-java-contrib](https://github.com/open-telemetry/opentelemetry-java-contrib/). -This feature is enabled by default and allows to capture a stacktrace for spans that have a duration above a threshold. +This feature is activated by default and allows to capture a stacktrace for spans that have a duration above a threshold. The `OTEL_JAVA_EXPERIMENTAL_SPAN_STACKTRACE_MIN_DURATION` configuration option, which defaults to `5ms`, allows to configure the minimal duration threshold. A negative value turns off the feature. -The `OTEL_JAVA_EXPERIMENTAL_SPAN_STACKTRACE_MIN_DURATION` configuration option (defaults to `5ms`) allows to configure the minimal duration threshold, a negative value will disable the feature. - -See [span-stacktrace](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/span-stacktrace) documentation for configuration options. +Refer to [span-stacktrace](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/span-stacktrace) for configuration options. ## Runtime metrics -Experimental runtime metrics are _enabled_ by default. - -Set `OTEL_INSTRUMENTATION_RUNTIME_TELEMETRY_EMIT_EXPERIMENTAL_TELEMETRY` to `false` to disable them. +Experimental runtime metrics are turned on by default. -## Metric Temporality +Set `OTEL_INSTRUMENTATION_RUNTIME_TELEMETRY_EMIT_EXPERIMENTAL_TELEMETRY` to `false` to turn them off. -Elasticsearch and Kibana work best with metrics provided in delta-temporality. -Therefore, the EDOT Java changes the default value of `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` to `DELTA`. -You can override this default if needed, note though that some provided Kibana dashboards will not work correctly in this case. +## Metric temporality -## Elastic Universal profiling integration +Elasticsearch and Kibana work best with metrics provided in delta-temporality. Therefore, the EDOT Java changes the default value of `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` to `DELTA`. You can override this default if needed, though some provided Kibana dashboards will not work correctly if you do it. -[Universal Profiling](https://www.elastic.co/observability/universal-profiling) integration provides the ability to correlate traces with profiling data from the Elastic universal profiler. +## Elastic Universal Profiling integration -This feature is enabled by default on supported systems, disabled otherwise. +[Universal Profiling](https://www.elastic.co/observability/universal-profiling) integration provides the ability to correlate traces with profiling data from the Elastic universal profiler. This feature is turned on by default on supported systems, and turned off otherwise. -See [universal-profiling-integration](https://github.com/elastic/elastic-otel-java/tree/main/universal-profiling-integration) for details and configuration options. +Refer to [universal-profiling-integration](https://github.com/elastic/elastic-otel-java/tree/main/universal-profiling-integration) for details and configuration options. diff --git a/docs/reference/edot-sdks/java/overhead.md b/docs/reference/edot-sdks/java/overhead.md index 5b599c8a..98b8c568 100644 --- a/docs/reference/edot-sdks/java/overhead.md +++ b/docs/reference/edot-sdks/java/overhead.md @@ -10,51 +10,41 @@ products: - id: observability - id: edot-java --- + # Performance overhead -While it is designed to and usually have minimal performance overhead, the EDOT Java agent, like any instrumentation agent, -executes within the application process and thus has a small influence on the application performance. +While designed to have minimal performance overhead, the EDOT Java agent, like any instrumentation agent, executes within the application process and thus has a small influence on the application performance. -This extra performance overhead depends on the application's technical architecture, its configuration and environment and -the load. Those factors are not something that are easy to reproduce on their own, and all applications are different so -it is impossible to provide a simple answer like "+1% extra CPU time and +100Mb of memory". +This performance overhead depends on the application's technical architecture, its configuration and environment, and the load. These factors are not easy to reproduce on their own, and all applications are different, so it is not possible to provide a simple answer. -The performance overhead on the JVM can be measured by the following high-level metrics: +You can measure the performance overhead on the JVM by using the following high-level metrics: -- application startup time -- application response time, which can be directly perceived by users +- Application startup time +- Application response time, which can be directly perceived by users - CPU usage - Garbage collector activity: more memory allocation means more GC activity, thus increasing overall CPU usage and potentially reducing application responsiveness - Memory usage: how much more memory (heap/non-heap) is needed -While we can't provide generically applicable, accurate numbers about the above, we execute synthetic benchmarks with a sample application -which allows to provide an estimate, comparison between agents and an order of magnitude of the effective overhead. +## Benchmark -Those numbers are only provided as indicators, and you should not attempt to extrapolate them. You should however use -them as a framework to evaluate and measure the overhead on your applications. +While Elastic can't provide generically applicable, accurate numbers about the impact on the previous metrics, synthetic benchmarks are executed with a sample application, which allows to provide an estimate and comparison between agents. Those numbers are only provided as indicators: use them as a framework to evaluate and measure the overhead on your applications. -For example, the application startup overhead going from 5s to 6s (+1s, +20%) does not mean an application having a startup time of -15s will now start in 18s but that you can expect to have about at least one extra second of startup time and the overall -impact remains limited. +For example, the application startup overhead going from 5s to 6s (+1s, +20%) does not mean an application having a startup time of 15s will now start in 18s but that you can expect to have about at least one extra second of startup time and the overall impact remains limited. -The following table compares the *classic Elastic APM Java Agent* with the `EDOT Java Agent` and the same benchmark without an agent. +The following table compares the classic Elastic APM Java Agent with the EDOT Java Agent and the same benchmark without an agent. -| | no agent | EDOT Java instrumentation | Elastic APM Java agent | +| | No agent | EDOT Java instrumentation | Elastic APM Java agent | |------------------------------|-----------|---------------------------|------------------------| -| startup time | 5.55 s | 6.82 s | 6.87 s | -| request latency (p95) | 1.96 ms | 2.06 ms | 2.08 ms | -| total system cpu utilization | 53.82 % | 54.25 % | 56.92 % | -| total allocated memory | 21.54 gb | 26.37 gb | 22.15 gb | -| total GC pauses | 106 ms | 123 ms | 120 ms | -| max heap used | 436.71 mb | 478.46 mb | 573.92 mb | +| Startup time | 5.55 s | 6.82 s | 6.87 s | +| Request latency (p95) | 1.96 ms | 2.06 ms | 2.08 ms | +| Total system cpu utilization | 53.82 % | 54.25 % | 56.92 % | +| Total allocated memory | 21.54 gb | 26.37 gb | 22.15 gb | +| Total GC pauses | 106 ms | 123 ms | 120 ms | +| Max heap used | 436.71 mb | 478.46 mb | 573.92 mb | -The main difference between the two agents is that unlike EDOT, Elastic APM Java agent recycles in-memory data -structures which allows to reduce the overall allocated memory and thus reduces a bit the overhead on the garbage collector. +The main difference between the two agents is that, unlike EDOT, Elastic APM Java agent recycles in-memory data structures which allows to reduce the overall allocated memory and thus reduces a bit the overhead on the garbage collector. -This difference is also the reason why we observe a difference in the maximum heap usage as more data structures are kept -in-memory when possible and not recycled by the garbage collector. This however does not mean that Elastic APM Java agent _requires_ -about 100mb more of memory compared to EDOT, but that when there is no limitation on heap memory usage the agent will -use available memory to minimize memory allocation. +This difference is also the reason why we observe a difference in the maximum heap usage as more data structures are kept in-memory when possible and not recycled by the garbage collector. This however does not mean that Elastic APM Java agent requires about 100mb more of memory compared to EDOT, but that when there is no limitation on heap memory usage the agent will use available memory to minimize memory allocation. ## Optimizing application startup @@ -64,14 +54,11 @@ With EDOT Java, the following resource attribute providers are enabled by defaul - GCP: [`OTEL_RESOURCE_PROVIDERS_GCP_ENABLED`](./configuration.md#configuration-options) = `true` - Azure: [`OTEL_RESOURCE_PROVIDERS_AZURE_ENABLED`](./configuration.md#configuration-options) = `true` -Because those resource attributes providers rely on metadata endpoints, they may require a few HTTP requests. -When the cloud provider is known or none is being used, it might be relevant to selectively disable them by setting -their respective configuration options to `false`. +Because those resource attributes providers rely on metadata endpoints, they might require a few HTTP requests. When the cloud provider is known or none is being used, it might be relevant to selectively turn them off by setting their respective configuration options to `false`. -Also, each enabled instrumentation adds instrumentation overhead, this can be controlled by applying one of the following strategies: +Also, each activated instrumentation adds instrumentation overhead. You can control this by applying one of the following strategies: -- [disable instrumentations selectively](https://opentelemetry.io/docs/zero-code/java/agent/disable/#suppressing-specific-agent-instrumentation) -- [disable all instrumentations and selectively enable the ones you need](https://opentelemetry.io/docs/zero-code/java/agent/disable/#enable-only-specific-instrumentation) +- [Turn off instrumentations selectively](https://opentelemetry.io/docs/zero-code/java/agent/disable/#suppressing-specific-agent-instrumentation). +- [Turn off all instrumentations and selectively turn on the ones you need](https://opentelemetry.io/docs/zero-code/java/agent/disable/#enable-only-specific-instrumentation). -However note that some instrumentation relies on other instrumentation to function properly. -When selectively **enabling** instrumentation, be sure to enable the transitive instrumentation dependencies too. +Note that some instrumentation relies on other instrumentation to function properly. When selectively turning on instrumentations, make sure to turn on the transitive instrumentation dependencies too. diff --git a/docs/reference/edot-sdks/java/setup/index.md b/docs/reference/edot-sdks/java/setup/index.md index e7d90ace..016de1bc 100644 --- a/docs/reference/edot-sdks/java/setup/index.md +++ b/docs/reference/edot-sdks/java/setup/index.md @@ -1,6 +1,6 @@ --- navigation_title: Setup -description: Instructions for setting up the Elastic Distribution of OpenTelemetry (EDOT) Java Agent in various environments, including Kubernetes and others. +description: Instructions for setting up the Elastic Distribution of OpenTelemetry (EDOT) Java in various environments, including Kubernetes and others. applies_to: stack: serverless: @@ -10,35 +10,38 @@ products: - id: observability - id: edot-java --- -# Setting up the EDOT Java Agent -**Kubernetes** +# Set up the EDOT Java Agent -For Kubernetes we recommend using the OTel Kubernetes Operator that also manages the auto-instrumentation of Java applications. Follow the [Quickstart Guide](../../../quickstart/index.md) for Kubernetes or learn more about [instrumentation details on Kubernetes for Java](./k8s.md). +Learn how to set up the Elastic Distribution of OpenTelemetry (EDOT) Java in various environments, including Kubernetes and others. -**All other environments** +## Kubernetes -Follow the Java setup guide below for all other environments. +For Kubernetes, use the OTel Kubernetes Operator. The Operator also manages the auto-instrumentation of Java applications. Follow the [Quickstart Guide](../../../quickstart/index.md) for Kubernetes or learn more about [instrumentation details on Kubernetes for Java](./k8s.md). -## Download +## All other environments -You can download the latest release version or snapshot version of the EDOT Java Agent from the following links: +Follow the following Java setup guide for all other environments. -| Latest Release | Latest Snapshot | +## Download the agent + +You can download the latest release version or snapshot version of the EDOT Java agent from the following links: + +| Latest release | Latest snapshot | |:---:|:---:| | [![Maven Central](https://img.shields.io/maven-central/v/co.elastic.otel/elastic-otel-javaagent?label=elastic-otel-javaagent&style=for-the-badge)](https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest) | [![Sonatype Nexus](https://img.shields.io/nexus/s/co.elastic.otel/elastic-otel-javaagent?server=https%3A%2F%2Foss.sonatype.org&label=elastic-otel-javaagent&style=for-the-badge)](https://oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=co.elastic.otel&a=elastic-otel-javaagent&v=LATEST) | ## Prerequisites -You need to have completed the steps in the [Quickstart](../../../quickstart/index.md) section that corresponds to your Elastic deployment model. +Complete the steps in the [Quickstart](../../../quickstart/index.md) section that corresponds to your Elastic deployment model. ## Configure the Java agent The minimal configuration to send data involves setting the values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` environment variables. -We also recommend setting the `service.name` resource attribute explicitly with `OTEL_SERVICE_NAME` as it allows to qualify captured data and group multiple service instances together. +Set the `service.name` resource attribute explicitly with `OTEL_SERVICE_NAME` as it allows to qualify captured data and group multiple service instances together. -Here is an example to set `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS` and `OTEL_SERVICE_NAME` environment variables: +The following is an example that sets the `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, and `OTEL_SERVICE_NAME` environment variables: ```sh export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io @@ -46,36 +49,32 @@ export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....l" export OTEL_SERVICE_NAME="my-awesome-service" ``` -For more advanced configuration, see [Configuration](../configuration.md) section. +For more advanced configuration, refer to [Configuration](../configuration.md). -Configuration of those environment values depends on the deployment model: +Configuration of those environment values depends on the deployment model. ### Local EDOT Collector -EDOT Collector is accessible with `http://localhost:4318` without authentication, no further configuration is required. -The `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` environment variables do not have to be set. +When deployed locally, the EDOT Collector is accessible with `http://localhost:4318` without authentication, no further configuration is required. The `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` environment variables do not have to be set. -**Self-managed EDOT Collector** +### Self-managed EDOT Collector -`OTEL_EXPORTER_OTLP_ENDPOINT` should be set to the OTLP endpoint of your self-managed EDOT Collector. - -If EDOT Collector requires authentication, `OTEL_EXPORTER_OTLP_HEADERS` should be set to include `Authorization=ApiKey ` (comma-separated key=value list). +When using a self-managed EDOT Collector, set the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable to the OTLP endpoint of your self-managed EDOT Collector. If EDOT Collector requires authentication, set `OTEL_EXPORTER_OTLP_HEADERS` to include `Authorization=ApiKey `. ### Elastic Managed OTLP endpoint -Use [these guides](../../../quickstart/serverless/index.md) to retrieve the `` and the ``. +Follow the [Serverless quickstart guides](../../../quickstart/serverless/index.md) to retrieve the `` and the ``. -- `OTEL_EXPORTER_OTLP_ENDPOINT` should be set to `` -- `OTEL_EXPORTER_OTLP_HEADERS` should be set to include `Authorization=ApiKey ` (comma-separated key=value list). +- Set `OTEL_EXPORTER_OTLP_ENDPOINT` to ``. +- Set `OTEL_EXPORTER_OTLP_HEADERS` to include `Authorization=ApiKey `. ### Kubernetes -Connection to the EDOT Collector is managed by the OTel Kubernetes Operator, [follow the Quickstart Guides](../../../quickstart/index.md) for Kubernetes. +Connection to the EDOT Collector is managed by the OTel Kubernetes Operator. [Follow the Quickstart Guides](../../../quickstart/index.md) for Kubernetes. ## Run the Java agent -Use the `-javaagent:` JVM argument with the path to agent jar, this requires to modify the JVM arguments and restart -the application. +Use the `-javaagent:` JVM argument with the path to agent jar. This requires to modify the JVM arguments and restart the application. ```sh java \ @@ -83,10 +82,8 @@ java \ -jar myapp.jar ``` -When modifying the JVM command line arguments is not possible, the `JAVA_TOOL_OPTIONS` environment variable can be used -to provide the `-javaagent:` argument or JVM system properties. When `JAVA_TOOL_OPTIONS` is set, all JVMs will automatically -use it, thus special care should be taken to limit the scope to the relevant JVMs. +When modifying the JVM command line arguments is not possible, use the `JAVA_TOOL_OPTIONS` environment variable to provide the `-javaagent:` argument or JVM system properties. When `JAVA_TOOL_OPTIONS` is set, all JVMs automatically use it, so make sure to limit the scope to the relevant JVMs. -Also, some application servers require manual steps or modification of their configuration files, see [dedicated instructions](https://opentelemetry.io/docs/zero-code/java/agent/server-config/) for more details. +Some application servers require manual steps or modification of their configuration files. Refer to [dedicated instructions](https://opentelemetry.io/docs/zero-code/java/agent/server-config/) for more details. -For applications deployed with Kubernetes, we recommend using [OpenTelemetry Operator](./k8s.md). +For applications deployed with Kubernetes, use the [OpenTelemetry Operator](./k8s.md). diff --git a/docs/reference/edot-sdks/java/setup/k8s.md b/docs/reference/edot-sdks/java/setup/k8s.md index ad6addaf..d10bd600 100644 --- a/docs/reference/edot-sdks/java/setup/k8s.md +++ b/docs/reference/edot-sdks/java/setup/k8s.md @@ -10,31 +10,32 @@ products: - id: observability - id: edot-java --- + # Instrumenting Java applications with EDOT SDKs on Kubernetes -This document focuses on instrumenting Java applications on Kubernetes, using the OpenTelemetry Operator, Elastic Distribution of OpenTelemetry (EDOT) Collectors, and the EDOT Java SDK. +Learn how to instrument Java applications on Kubernetes using the OpenTelemetry Operator, the Elastic Distribution of OpenTelemetry (EDOT) Collectors, and the EDOT Java SDK. - For general knowledge about the EDOT Java SDK, refer to the [EDOT Java Intro page](../index.md). - For Java auto-instrumentation specifics, refer to [OpenTelemetry Operator Java auto-instrumentation](https://opentelemetry.io/docs/kubernetes/operator/automatic/#java). - For general information about instrumenting applications on Kubernetes, refer to [instrumenting applications on Kubernetes](../../../use-cases/kubernetes/instrumenting-applications.md). -## Java agent extensions consideration +## Extensions consideration The operator supports a configuration that installs [Java agent extensions](https://opentelemetry.io/docs/zero-code/java/agent/extensions/) in `Instrumentation` objects. The extension needs to be available in an image. Refer to [using extensions with the OpenTelemetry Java agent](https://www.elastic.co/observability-labs/blog/using-the-otel-operator-for-injecting-elastic-agents#using-an-extension-with-the-opentelemetry-java-agent) for an example of adding an extension to an agent. -## Instrument a Java app with EDOT Java SDK on Kubernetes +## Instrument a Java app -In this example, you'll learn how to: +Following this example, you can learn how to: -- Enable auto-instrumentation of a Java application using one of the following supported methods: +- Turn on auto-instrumentation of a Java application using one of the following supported methods: - Adding an annotation to the deployment Pods. - Adding an annotation to the namespace. - Verify that auto-instrumentation libraries are injected and configured correctly. -- Confirm data is flowing to **Kibana Observability**. +- Confirm data is flowing to Kibana Observability. -For this example, we assume the application you're instrumenting is a deployment named `java-app` running in the `java-ns` namespace. +In this example, the application you're instrumenting is a deployment named `java-app` running in the `java-ns` namespace. -1. Ensure you have successfully [installed the OpenTelemetry Operator](../../../use-cases/kubernetes/deployment.md), and confirm that the following `Instrumentation` object exists in the system: +1. Ensure you have successfully [installed the OpenTelemetry Operator](../../../use-cases/kubernetes/deployment.md) and confirm that the following `Instrumentation` object exists in the system: ```sh $ kubectl get instrumentation -n opentelemetry-operator-system @@ -42,11 +43,11 @@ For this example, we assume the application you're instrumenting is a deployment elastic-instrumentation 107s http://opentelemetry-kube-stack-daemon-collector.opentelemetry-operator-system.svc.cluster.local:4318 ``` -:::{note} -> If your `Instrumentation` object has a different name or is created in a different namespace, you will have to adapt the annotation value in the next step. -::: + :::{note} + If your `Instrumentation` object has a different name or is created in a different namespace, you will have to adapt the annotation value in the next step. + ::: -2. Enable auto-instrumentation of your Java application using one of the following methods: +2. Turn on auto-instrumentation of your Java application using one of the following methods: - Edit your application workload definition and include the annotation under `spec.template.metadata.annotations`: @@ -71,9 +72,9 @@ For this example, we assume the application you're instrumenting is a deployment kubectl annotate namespace java-ns instrumentation.opentelemetry.io/inject-java=opentelemetry-operator-system/elastic-instrumentation ``` -3. Restart application +3. Restart the application - Once the annotation has been set, restart the application to create new Pods and inject the instrumentation libraries: + After the annotation has been set, restart the application to create new Pods and inject the instrumentation libraries: ```sh kubectl rollout restart deployment java-app -n java-ns @@ -151,15 +152,15 @@ For this example, we assume the application you're instrumenting is a deployment Ensure the environment variable `OTEL_EXPORTER_OTLP_ENDPOINT` points to a valid endpoint and there's network communication between the Pod and the endpoint. -5. Confirm data is flowing to **Kibana**: +5. Confirm data is flowing to Kibana: - - Open **Observability** -> **Applications** -> **Service inventory**, and determine if: + - Open **Observability**, **Applications**, **Service inventory**, and determine if: - The application appears in the list of services. - The application shows transactions and metrics. - - For application container logs, open **Kibana Discover** and filter for your Pods' logs. In the provided example, we could filter for them with either of the following: - - `k8s.deployment.name: "java-app"` (**adapt the query filter to your use case**) - - `k8s.pod.name: java-app*` (**adapt the query filter to your use case**) + - For application container logs, open Kibana Discover and filter for your Pods' logs. In the provided example, we could filter for them with either of the following: + - `k8s.deployment.name: "java-app"` (adapt the query filter to your use case) + - `k8s.pod.name: java-app*` (adapt the query filter to your use case) Note that the container logs are not provided by the instrumentation library, but by the DaemonSet collector deployed as part of the [operator installation](../../../use-cases/kubernetes/deployment.md). diff --git a/docs/reference/edot-sdks/nodejs/configuration.md b/docs/reference/edot-sdks/nodejs/configuration.md index f8f6180a..6e50793d 100644 --- a/docs/reference/edot-sdks/nodejs/configuration.md +++ b/docs/reference/edot-sdks/nodejs/configuration.md @@ -11,7 +11,7 @@ products: - id: edot-nodejs --- -# Configuring the EDOT Node.js SDK +# Configure the EDOT Node.js SDK The Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) is configured with environment variables beginning with `OTEL_` or `ELASTIC_OTEL_`. Any `OTEL_*` environment variables behave the same as with the upstream OpenTelemetry SDK. For example, all the OpenTelemetry [General SDK Configuration env vars](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) are supported. If EDOT Node.js provides a configuration setting specific to the Elastic distribution, it will begin with `ELASTIC_OTEL_`. diff --git a/docs/reference/edot-sdks/nodejs/setup/index.md b/docs/reference/edot-sdks/nodejs/setup/index.md index 261bf982..4685cea4 100644 --- a/docs/reference/edot-sdks/nodejs/setup/index.md +++ b/docs/reference/edot-sdks/nodejs/setup/index.md @@ -11,9 +11,11 @@ products: - id: edot-nodejs --- -# Setting up EDOT Node.js +# Set up EDOT Node.js -To monitor your service with the Elastic Distribution of OpenTelemetry Node.js (EDOT Node.js) you'll need to install it, configure it, and properly start it with your application. For example, this shows the minimal steps: +To monitor your service with the Elastic Distribution of OpenTelemetry (EDOT) Node.js you need to install it, configure it, and properly start it with your application. + +For example, the following commands perform the minimal setup steps: ```bash # Install it @@ -28,15 +30,13 @@ export OTEL_SERVICE_NAME="my-app" node --import @elastic/opentelemetry-node my-app.js ``` -This setup guide covers each of these steps. (If you are deploying in Kubernetes, see the [Kubernetes setup guide](./k8s.md).) - +If you are deploying in Kubernetes, see the [Kubernetes setup guide](./k8s.md). ## Prerequisites -Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an Elastic Observability deployment. You can use an existing one or set up a new one. - -Follow the EDOT [Quickstart guide](../../../quickstart/index.md) to get a deployment and gather the `ELASTIC_OTLP_ENDPOINT` and `ELASTIC_API_KEY` pieces of data that you'll need to configure the EDOT Node.js SDK. +Before getting started, you need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an Elastic Observability deployment. You can use an existing one or set up a new one. +Follow the EDOT [Quickstart guide](../../../quickstart/index.md) to get a deployment and gather the `ELASTIC_OTLP_ENDPOINT` and `ELASTIC_API_KEY` pieces of data that you need to configure the EDOT Node.js SDK. ## Installation @@ -50,23 +50,25 @@ pnpm add @elastic/opentelemetry-node ## Configuration -EDOT Node.js is configured with environment variables beginning with `OTEL_` or `ELASTIC_OTEL_`. Any `OTEL_*` environment variables behave the same as with the upstream OpenTelemetry SDK. For example, all the OpenTelemetry [General SDK Configuration env vars](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) are supported. If EDOT Node.js provides a configuration setting specific to the Elastic distribution, it will begin with `ELASTIC_OTEL_`. +EDOT Node.js is configured with environment variables beginning with `OTEL_` or `ELASTIC_OTEL_`. Any `OTEL_*` environment variables behave the same as with the upstream OpenTelemetry SDK. + +For example, all the OpenTelemetry [General SDK Configuration env vars](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) are supported. If EDOT Node.js provides a configuration setting specific to the Elastic distribution, it begins with `ELASTIC_OTEL_`. ### Basic configuration -To configure EDOT Node.js, as a typical minimum you will need: +To configure EDOT Node.js, as a typical minimum you need: -* `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of an OpenTelemetry Collector where data will be sent. When using Elastic Observability, this will be the "ingest" endpoint of an Elastic Cloud Serverless project or the URL of a deployed [EDOT Collector](../../../edot-collector/index.md) **Set this to the `ELASTIC_OTLP_ENDPOINT` value as described in the [EDOT Quickstart pages](../../../quickstart/index.md).** -* `OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of HTTP headers used for exporting data, typically used to set the `Authorization` header with auth information. **Get an `ELASTIC_API_KEY` as described in the [EDOT Quickstart pages](../../../quickstart/index.md) and set this to `"Authorization=ApiKey ELASTIC_API_KEY"`.** -* `OTEL_SERVICE_NAME`: The name of your service, used to distinguish telemetry data from other services in your system. If not set, it will default to `unknown_service:node`. +* `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of an OpenTelemetry Collector where data is sent. When using Elastic Observability, this is the ingest endpoint of an Elastic Cloud Serverless project or the URL of a deployed [EDOT Collector](../../../edot-collector/index.md). Set this to the `ELASTIC_OTLP_ENDPOINT` value as described in the [EDOT Quickstart pages](../../../quickstart/index.md). +* `OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of HTTP headers used for exporting data, typically used to set the `Authorization` header with auth information. Get an `ELASTIC_API_KEY` as described in the [EDOT Quickstart pages](../../../quickstart/index.md) and set this to `"Authorization=ApiKey ELASTIC_API_KEY"`. +* `OTEL_SERVICE_NAME`: The name of your service, used to distinguish telemetry data from other services in your system. If not set, it defaults to `unknown_service:node`. :::{note} -In some environments, for example in some Kubernetes setups, a *local* OpenTelemetry Collector (e.g. EDOT Collector) is deployed with an endpoint of `http://localhost:4318`. This is the default exporter endpoint used by EDOT Node.js. In this case the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable does not need to be set. +In some environments, for example in some Kubernetes setups, a local OpenTelemetry Collector is deployed with an endpoint of `http://localhost:4318`. This is the default exporter endpoint used by EDOT Node.js. In this case the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable does not need to be set. ::: -### Additional common configuration +### Additional configuration -Some other common configuration settings that are good to know: +Additional other common configuration settings that might be useful include: * `OTEL_RESOURCE_ATTRIBUTES=service.version=,deployment.environment=production`: This environment variable can be used to set additional [Resource attributes](https://opentelemetry.io/docs/languages/js/resources/). Setting `service.version` can be useful for correlating issues to different versions of your service. Setting `deployment.environment` can be useful for separating telemetry for development, test, qa, or production deployments of your services. * `OTEL_NODE_DISABLED_INSTRUMENTATIONS=net,dns,...`: A comma-separated list of instrumentation names to disable. This can be useful if a particular instrumentation is unwanted for some reason. @@ -75,10 +77,9 @@ Some other common configuration settings that are good to know: For more information on all the available configuration options, refer to [Configuration](../configuration.md). - ## Start EDOT Node.js -For EDOT Node.js to automatically instrument modules used by your Node.js service, it must be started before you `require` or `import` your service code's dependencies -- for example, before `express` or `http` are loaded. +For EDOT Node.js to automatically instrument modules used by your Node.js service, start it before you `require` or `import` your service code's dependencies. For example, before `express` or `http` are loaded. The recommended way to start EDOT Node.js is by using the `--import` Node.js [CLI option](https://nodejs.org/api/cli.html#--importmodule). This loads and starts the SDK in Node.js' "preload" phase, which ensures that it is started before any application modules. @@ -86,24 +87,22 @@ The recommended way to start EDOT Node.js is by using the `--import` Node.js [CL node --import @elastic/opentelemetry-node my-app.js ``` -This `--import` option can also be specified in the `NODE_OPTIONS` environment variable: +You can also specify the `--import` option in the `NODE_OPTIONS` environment variable: ```bash export NODE_OPTIONS="--import @elastic/opentelemetry-node" node my-app.js ``` - - -EDOT Node.js will automatically instrument popular modules (listed in [Supported technologies](../supported-technologies.md)) used by your service, and send traces, metrics, and logs telemetry data (using OTLP) to your configured observability backend. +EDOT Node.js automatically instruments popular modules, listed in [Supported technologies](../supported-technologies.md), used by your service, and send traces, metrics, and logs telemetry data (using OTLP) to your configured observability backend. ## Confirm instrumentation is working To confirm that EDOT Node.js has be setup successfully: 1. Call your running service to ensure it has had some activity that EDOT Node.js can trace. -2. Go to **Applications** → **Service Inventory** in your Elastic deployment. -3. You should see the name of your service. (It can take a minute or two after starting your service with EDOT Node.js for the service to show up in this list.) +2. Go to **Applications**, **Service Inventory** in your Elastic Observability deployment. +3. Find the name of your service. It can take a minute or two after starting your service with EDOT Node.js for the service to show up in this list. If you do not see your service, work through [the Troubleshooting guide](../troubleshooting.md). diff --git a/docs/reference/edot-sdks/nodejs/setup/k8s.md b/docs/reference/edot-sdks/nodejs/setup/k8s.md index ef773926..040931b6 100644 --- a/docs/reference/edot-sdks/nodejs/setup/k8s.md +++ b/docs/reference/edot-sdks/nodejs/setup/k8s.md @@ -13,155 +13,156 @@ products: # Instrumenting Node.js applications with EDOT SDKs on Kubernetes -This document focuses on instrumenting Node.js applications on Kubernetes, using the OpenTelemetry Operator, the Elastic Distribution of OpenTelemetry (EDOT) Collectors, and the EDOT Node.js SDK. +Learn how to instrument Node.js applications on Kubernetes, using the OpenTelemetry Operator, the Elastic Distribution of OpenTelemetry (EDOT) Collectors, and the EDOT Node.js SDK. - For general knowledge about the EDOT Node.js SDK, refer to the [EDOT Node.js Intro page](../index.md) and [Configuration](../configuration.md). - For Node.js auto-instrumentation specifics, refer to [OpenTelemetry Operator Node.js auto-instrumentation](https://opentelemetry.io/docs/kubernetes/operator/automatic/#nodejs). - For general information about instrumenting applications on Kubernetes, refer to [instrumenting applications on Kubernetes](../../../use-cases/kubernetes/instrumenting-applications.md). -## Instrument a Node.js app with EDOT Node.js SDK on Kubernetes +## Instrument a Node.js app on Kubernetes -In this example, you'll learn how to: +::::::{stepper} -- Enable auto-instrumentation of a Node.js application using one of the following supported methods: - - Adding an annotation to the deployment Pods. - - Adding an annotation to the namespace. -- Verify that auto-instrumentation libraries are injected and configured correctly. -- Confirm data is flowing to **Kibana Observability**. +::::{step} Ensure the OpenTelemetry Operator and Instrumentation object exist +Ensure you have successfully [installed the OpenTelemetry Operator](../../../use-cases/kubernetes/deployment.md), and confirm that the following `Instrumentation` object exists in the system: -For this example, we assume the application you're instrumenting is a deployment named `nodejs-app` running in the `nodejs-ns` namespace. +```bash +$ kubectl get instrumentation -n opentelemetry-operator-system +NAME AGE ENDPOINT +elastic-instrumentation 107s http://opentelemetry-kube-stack-daemon-collector.opentelemetry-operator-system.svc.cluster.local:4318 +``` -1. Ensure you have successfully [installed the OpenTelemetry Operator](../../../use-cases/kubernetes/deployment.md), and confirm that the following `Instrumentation` object exists in the system: +:::{note} +If your `Instrumentation` object has a different name or is created in a different namespace, you will have to adapt the annotation value in the next step. +::: +:::: - ```bash - $ kubectl get instrumentation -n opentelemetry-operator-system - NAME AGE ENDPOINT - elastic-instrumentation 107s http://opentelemetry-kube-stack-daemon-collector.opentelemetry-operator-system.svc.cluster.local:4318 - ``` +::::{step} Enable auto-instrumentation for your Node.js application +Enable auto-instrumentation of your Node.js application using one of the following methods: + +- Edit your application workload definition and include the annotation under `spec.template.metadata.annotations`: + + ```yaml + kind: Deployment + metadata: + name: nodejs-app + namespace: nodejs-ns + spec: + ... + template: + metadata: + ... + annotations: + instrumentation.opentelemetry.io/inject-nodejs: opentelemetry-operator-system/elastic-instrumentation + ... + ``` + +- Alternatively, add the annotation at namespace level to apply auto-instrumentation in all Pods of the namespace: + + ```bash + kubectl annotate namespace nodejs-ns instrumentation.opentelemetry.io/inject-nodejs=opentelemetry-operator-system/elastic-instrumentation + ``` +:::: + +::::{step} Restart your application +Once the annotation has been set, restart the application to create new Pods and inject the instrumentation libraries: + + ```bash + kubectl rollout restart deployment nodejs-app -n nodejs-ns + ``` +:::: + +::::{step} Verify auto-instrumentation resources in the Pods +Verify the [auto-instrumentation resources](../../../use-cases/kubernetes/instrumenting-applications.md#how-auto-instrumentation-works) are injected in the Pods: + +Run a `kubectl describe` of one of your application Pods and check: + +- There should be an init container named `opentelemetry-auto-instrumentation-nodejs` in the Pod. For example: + + ```bash + $ kubectl describe pod nodejs-app-8d84c47b8-8h5z2 -n nodejs-ns + Name: nodejs-app-8d84c47b8-8h5z2 + Namespace: nodejs-ns + ... + ... + Init Containers: + opentelemetry-auto-instrumentation-nodejs: + Container ID: containerd://cbf67d7ca1bd62c25614b905a11e81405bed6fd215f2df21f84b90fd0279230b + Image: docker.elastic.co/observability/elastic-otel-node:0.5.0 + Command: + cp + -r + /autoinstrumentation/. + /otel-auto-instrumentation-nodejs + State: Terminated + Reason: Completed + Exit Code: 0 + Started: Wed, 13 Nov 2024 15:47:02 +0100 + Finished: Wed, 13 Nov 2024 15:47:03 +0100 + Ready: True + Restart Count: 0 + Environment: + Mounts: + /otel-auto-instrumentation-nodejs from opentelemetry-auto-instrumentation-nodejs (rw) + /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-swhn5 (ro) + ``` + +- The main container of the deployment loads the SDK through the `NODE_OPTIONS` environment variable: + + ```bash + ... + Containers: + nodejs-app: + Environment: + ... + NODE_OPTIONS: --require /otel-auto-instrumentation-nodejs/autoinstrumentation.js + OTEL_SERVICE_NAME: nodejs-app + OTEL_EXPORTER_OTLP_ENDPOINT: http://opentelemetry-kube-stack-daemon-collector.opentelemetry-operator-system.svc.cluster.local:4318 + ... + ``` + + Ensure the environment variable `OTEL_EXPORTER_OTLP_ENDPOINT` points to a valid endpoint and there's network communication between the Pod and the endpoint. + +- The Pod has an `EmptyDir` volume named `opentelemetry-auto-instrumentation-nodejs` mounted in both the main and the init containers in path `/otel-auto-instrumentation-nodejs`. + + ```bash + Init Containers: + opentelemetry-auto-instrumentation-nodejs: + ... + Mounts: + /otel-auto-instrumentation-nodejs from opentelemetry-auto-instrumentation-nodejs (rw) + Containers: + nodejs-app: + ... + Mounts: + /otel-auto-instrumentation-nodejs from opentelemetry-auto-instrumentation-nodejs (rw) + ... + Volumes: + ... + opentelemetry-auto-instrumentation-nodejs: + Type: EmptyDir (a temporary directory that shares a pod's lifetime) + ``` +:::: + +::::{step} Confirm data is flowing to Kibana +Confirm data is flowing to **Kibana**: + +- Open **Observability**, **Applications**, **Service inventory**, and determine if: + - The application appears in the list of services (`nodejs-app` in the example). + - The application shows transactions and metrics. :::{note} - If your `Instrumentation` object has a different name or is created in a different namespace, you will have to adapt the annotation value in the next step. + You may need to generate traffic to your application to see spans and metrics. ::: -2. Enable auto-instrumentation of your Node.js application using one of the following methods: +- For application container logs, open **Kibana Discover** and filter for your Pods' logs. In the provided example, you could filter for them with either of the following: + - `k8s.deployment.name: "nodejs-app"` (adapt the query filter to your use case). + - `k8s.pod.name: nodejs-app*` (adapt the query filter to your use case). - - Edit your application workload definition and include the annotation under `spec.template.metadata.annotations`: +Note that the container logs are not provided by the instrumentation library, but by the DaemonSet collector deployed as part of the [operator installation](../../../use-cases/kubernetes/deployment.md). +:::: - ```yaml - kind: Deployment - metadata: - name: nodejs-app - namespace: nodejs-ns - spec: - ... - template: - metadata: - ... - annotations: - instrumentation.opentelemetry.io/inject-nodejs: opentelemetry-operator-system/elastic-instrumentation - ... - ``` - - - Alternatively, add the annotation at namespace level to apply auto-instrumentation in all Pods of the namespace: - - ```bash - kubectl annotate namespace nodejs-ns instrumentation.opentelemetry.io/inject-nodejs=opentelemetry-operator-system/elastic-instrumentation - ``` - -3. Restart application - - Once the annotation has been set, restart the application to create new Pods and inject the instrumentation libraries: - - ```bash - kubectl rollout restart deployment nodejs-app -n nodejs-ns - ``` - -4. Verify the [auto-instrumentation resources](../../../use-cases/kubernetes/instrumenting-applications.md#how-auto-instrumentation-works) are injected in the Pods: - - Run a `kubectl describe` of one of your application Pods and check: - - - There should be an init container named `opentelemetry-auto-instrumentation-nodejs` in the Pod. For example: - - ```bash - $ kubectl describe pod nodejs-app-8d84c47b8-8h5z2 -n nodejs-ns - Name: nodejs-app-8d84c47b8-8h5z2 - Namespace: nodejs-ns - ... - ... - Init Containers: - opentelemetry-auto-instrumentation-nodejs: - Container ID: containerd://cbf67d7ca1bd62c25614b905a11e81405bed6fd215f2df21f84b90fd0279230b - Image: docker.elastic.co/observability/elastic-otel-node:0.5.0 - Command: - cp - -r - /autoinstrumentation/. - /otel-auto-instrumentation-nodejs - State: Terminated - Reason: Completed - Exit Code: 0 - Started: Wed, 13 Nov 2024 15:47:02 +0100 - Finished: Wed, 13 Nov 2024 15:47:03 +0100 - Ready: True - Restart Count: 0 - Environment: - Mounts: - /otel-auto-instrumentation-nodejs from opentelemetry-auto-instrumentation-nodejs (rw) - /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-swhn5 (ro) - ``` - - - The main container of the deployment loads the SDK through the `NODE_OPTIONS` environment variable: - - ```bash - ... - Containers: - nodejs-app: - Environment: - ... - NODE_OPTIONS: --require /otel-auto-instrumentation-nodejs/autoinstrumentation.js - OTEL_SERVICE_NAME: nodejs-app - OTEL_EXPORTER_OTLP_ENDPOINT: http://opentelemetry-kube-stack-daemon-collector.opentelemetry-operator-system.svc.cluster.local:4318 - ... - ``` - - Ensure the environment variable `OTEL_EXPORTER_OTLP_ENDPOINT` points to a valid endpoint and there's network communication between the Pod and the endpoint. - - - The Pod has an `EmptyDir` volume named `opentelemetry-auto-instrumentation-nodejs` mounted in both the main and the init containers in path `/otel-auto-instrumentation-nodejs`. - - ```bash - Init Containers: - opentelemetry-auto-instrumentation-nodejs: - ... - Mounts: - /otel-auto-instrumentation-nodejs from opentelemetry-auto-instrumentation-nodejs (rw) - Containers: - nodejs-app: - ... - Mounts: - /otel-auto-instrumentation-nodejs from opentelemetry-auto-instrumentation-nodejs (rw) - ... - Volumes: - ... - opentelemetry-auto-instrumentation-nodejs: - Type: EmptyDir (a temporary directory that shares a pod's lifetime) - ``` - -5. Confirm data is flowing to **Kibana**: - - - Open **Observability** -> **Applications** -> **Service inventory**, and determine if: - - The application appears in the list of services (`nodejs-app` in the example). - - The application shows transactions and metrics. - - - :::{note} - You may need to generate traffic to your application to see spans and metrics. - ::: - - - For application container logs, open **Kibana Discover** and filter for your Pods' logs. In the provided example, we could filter for them with either of the following: - - `k8s.deployment.name: "nodejs-app"` (**adapt the query filter to your use case**) - - `k8s.pod.name: nodejs-app*` (**adapt the query filter to your use case**) - - Note that the container logs are not provided by the instrumentation library, but by the DaemonSet collector deployed as part of the [operator installation](../../../use-cases/kubernetes/deployment.md). +:::::: ## Troubleshooting diff --git a/docs/reference/edot-sdks/php/configuration.md b/docs/reference/edot-sdks/php/configuration.md index cdd18c1d..17bca339 100644 --- a/docs/reference/edot-sdks/php/configuration.md +++ b/docs/reference/edot-sdks/php/configuration.md @@ -11,13 +11,13 @@ products: - id: edot-php --- -# Configuring the EDOT PHP SDK +# Configure the EDOT PHP SDK -Configure the Elastic Distribution of OpenTelemetry PHP (EDOT PHP) to send data to Elastic. +Learn how to configure the Elastic Distribution of OpenTelemetry PHP (EDOT PHP) to send data to Elastic. ## Configuration method -Configuration of the OpenTelemetry SDK should be performed through the mechanisms [documented on the OpenTelemetry website](https://opentelemetry.io/docs/zero-code/php#configuration). EDOT PHP is typically configured with `OTEL_*` environment variables defined by the OpenTelemetry spec. For example: +You can configure the OpenTelemetry SDK through the mechanisms [documented on the OpenTelemetry website](https://opentelemetry.io/docs/zero-code/php#configuration). EDOT PHP is typically configured with `OTEL_*` environment variables defined by the OpenTelemetry spec. For example: ```bash export OTEL_EXPORTER_OTLP_ENDPOINT="https://********.cloud.es.io:443/" @@ -46,59 +46,50 @@ The most important OpenTelemetry options you should be aware of include: | [OTEL_TRACES_SAMPLER_ARG](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler_arg) | | string or number | Provides an argument to the configured traces sampler, such as the sampling ratio for `traceidratio` (e.g., `0.25` for 25% sampling). | | [OTEL_LOG_LEVEL](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) | "info" | "error", "warn", "info", "debug" | Sets the verbosity level of the OpenTelemetry SDK’s internal logging. Useful for debugging configuration or troubleshooting instrumentation. | -:::{note} Reference For full configuration options of PHP SDK, see the official [OpenTelemetry PHP SDK Configuration documentation](https://opentelemetry.io/docs/languages/php/sdk/#configuration). -::: - -:::{note} -EDOT PHP sets the `OTEL_PHP_AUTOLOAD_ENABLED` option to `true` by default. -This enables automatic instrumentation without requiring any changes to your application code. -Modifying this option will have no effect — EDOT will override it and enforce it as `true`. -::: - -:::{note} Note on EDOT PHP background sending -EDOT PHP supports background data transmission (non-blocking export), but **only when the exporter is set to `http/protobuf` (OTLP over HTTP)** — which is the default configuration. -If you change the exporter or the transport protocol (e.g., to gRPC or another format), telemetry data will be sent **synchronously**, potentially impacting request latency. -::: -### Configuration options only available in EDOT PHP +### Special considerations -In addition to general OpenTelemetry configuration options, there are two kinds of configuration options that are _only_ available in EDOT PHP. +EDOT PHP supports background data transmission (non-blocking export), but only when the exporter is set to `http/protobuf` (OTLP over HTTP), which is the default configuration. +If you change the exporter or the transport protocol, for example to gRPC or another format, telemetry data will be sent synchronously, potentially impacting request latency. -**Elastic-authored options that are not yet available upstream** +EDOT PHP also sets the `OTEL_PHP_AUTOLOAD_ENABLED` option to `true` by default. This turns on automatic instrumentation without requiring any changes to your application code. +Modifying this option will have no effect: EDOT will override it and enforce it as `true`. -Additional `OTEL_` options that Elastic plans to contribute upstream to the OpenTelemetry PHP SDK, but are not yet available in the OpenTelemetry PHP SDK. +### Options only available in EDOT PHP -_Currently there are no additional `OTEL_` options waiting to be contributed upstream._ - -**Elastic-specific options** +In addition to general OpenTelemetry configuration options, there are two kinds of configuration options that are only available in EDOT PHP. Each option listed in this document that starts with the `ELASTIC_OTEL_` prefix can be set using either an environment variable or the `php.ini` file. When using the `php.ini` file, replace the `ELASTIC_OTEL_` prefix with `elastic_otel.` and convert the rest of the option name to lowercase, for example: -Configuration using an environment variable: +::::{tab-set} +:::{tab-item} Environment variable ```bash export ELASTIC_OTEL_ENABLED=true ``` +::: -Configuration using php.ini: - +:::{tab-item} php.ini ```ini elastic_otel.enabled=true ``` +::: + +:::: -`ELASTIC_OTEL_` options that are specific to Elastic and will always live in EDOT PHP (in other words, they will _not_ be added upstream): +`ELASTIC_OTEL_` options that are specific to Elastic and always live in EDOT PHP, meaning they will not be added to upstream, include the following. -#### General configuration #### +#### General configuration | Option(s) | Default | Accepted values | Description | | -------------------- | ------- | --------------- | ----------------------------------------------------------- | | ELASTIC_OTEL_ENABLED | true | true or false | Enables the automatic bootstrapping of instrumentation code | | ELASTIC_OTEL_NATIVE_OTLP_SERIALIZER_ENABLED | true | true or false | Enables the native built-in OTLP Protobuf serializer for maximum performance | -#### Asynchronous data sending configuration #### +#### Asynchronous data sending configuration | Option(s) | Default | Accepted values | Description | | --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | @@ -107,7 +98,7 @@ elastic_otel.enabled=true | ELASTIC_OTEL_MAX_SEND_QUEUE_SIZE | 2MB | integer number with optional units: B, MB or GB | Set the maximum buffer size for asynchronous (background) transfer. It is set per worker process. | | ELASTIC_OTEL_VERIFY_SERVER_CERT | true | true or false | Enables server certificate verification for asynchronous sending | -#### Logging configuration #### +#### Logging configuration | Option(s) | Default | Accepted values | Description | | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -117,7 +108,7 @@ elastic_otel.enabled=true | ELASTIC_OTEL_LOG_LEVEL_SYSLOG | OFF | OFF, CRITICAL, ERROR, WARNING, INFO, DEBUG, TRACE | Log level for file sink. Set to OFF if you don't want to log to file. This sink is recommended when you don't have write access to file system. | | ELASTIC_OTEL_LOG_FEATURES | | Comma separated string with FEATURE=LEVEL pairs.
Supported features:
ALL, MODULE, REQUEST, TRANSPORT, BOOTSTRAP, HOOKS, INSTRUMENTATION | Allows selective setting of log level for features. For example, "ALL=info,TRANSPORT=trace" will result in all other features logging at the info level, while the TRANSPORT feature logs at the trace level. It should be noted that the appropriate log level must be set for the sink - for our example, this would be TRACE. | -#### Transaction span configuration #### +#### Transaction span configuration | Option(s) | Default | Accepted values | Description | | ----------------------------------------- | --------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -126,7 +117,7 @@ elastic_otel.enabled=true | ELASTIC_OTEL_TRANSACTION_URL_GROUPS | | Comma-separated list of wildcard expressions | Allows grouping multiple URL paths using wildcard expressions, such as `/user/*`. For example, `/user/Alice` and `/user/Bob` will be mapped to the transaction name `/user/*`. | |