From c40f2593729c08ad6d3dc8163400923ce88508ca Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Tue, 26 Aug 2025 20:35:41 +0200 Subject: [PATCH 1/5] Add EDOT SDK debug logging guide --- .../edot-sdks/enable-debug-logging.md | 154 ++++++++++++++++++ troubleshoot/ingest/opentelemetry/toc.yml | 1 + 2 files changed, 155 insertions(+) create mode 100644 troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md diff --git a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md new file mode 100644 index 0000000000..9e38d58cb9 --- /dev/null +++ b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md @@ -0,0 +1,154 @@ +--- +navigation_title: Enable debug logging for SDKs +description: Learn how to enable debug logging for EDOT SDKs to troubleshoot application-level instrumentation issues. +applies_to: + stack: + serverless: + observability: + product: + edot_sdk: ga +products: + - id: cloud-serverless + - id: observability + - id: edot-sdk +--- + +# Enable debug logging for EDOT SDKs + +You can enable debug logging for Elastic Distributions of OpenTelemetry (EDOT) SDKs to troubleshoot application-level issues. + +Enabling debug logging can help surface common problems such as: + +* Auto-instrumentation not attaching or being disabled +* Authentication or endpoint misconfigurations +* Unsupported framework or language version +* Sampling rate being set too low (resulting in missing spans) + +## General SDK troubleshooting tips + +Check your application logs for SDK-specific output and errors. If no logs appear at all, verify that: + +* The SDK or agent is correctly installed and loaded +* The application runtime includes the correct path or classpath +* The environment variables are visible to the application process +* The logs are being written to the correct location + +:::{{warning}} +Debug logs can be verbose, potentially impacting performance and containing sensitive information such as system paths, variable names, or internal data structures. They shouldn't be enabled in production environments. +::: + + +## Java + +You can enable debug logging using environment variables. + +For general EDOT Java agent debugging, try: + +```bash +export OTEL_JAVAAGENT_LOG_LEVEL=debug +java -jar your-app.jar +``` +The output is captured span information from the agent itself, in a JSON format. + +If you need to see and inspect the specific trace data your application is generating, use: + + +```bash +export OTEL_TRACES_EXPORTER=otlp,logging-otlp +java -jar your-app.jar +``` + +The output are the application’s traces in a JSON format. + +By default, logs are written to `stderr`. + + +## Python + +To enable debug logging, set the `OTEL_PYTHON_LOG_LEVEL` variable to `debug`: + +```bash +export OTEL_PYTHON_LOG_LEVEL=debug +``` + +Run your application as usual, for example: + +```bash +python your_application.py +``` + + +## .NET + +To enable debug logging for the EDOT .NET agent, set: + +::::{tab-set} + +:::{tab-item} macOS + +```bash +export OTEL_LOG_LEVEL=debug +``` +::: + +:::{tab-item} Windows + +```powershell +$env:OTEL_LOG_LEVEL="debug" +``` +::: +:::: + + +## Node.js + +Set this environment variable before starting your app: + +::::{tab-set} + +:::{tab-item} macOS + +```bash +export OTEL_LOG_LEVEL=debug +node your-app.js +``` +::: + +:::{tab-item} Windows + +```powershell +$env:OTEL_LOG_LEVEL="debug" +node your-app.js +``` +::: +:::: + + +## PHP + +Set this environment variable: + +::::{tab-set} + +:::{tab-item} macOS + +```bash +export OTEL_LOG_LEVEL=debug +php your-application.php +``` +::: + +:::{tab-item} Windows + +```powershell +$env:OTEL_LOG_LEVEL="debug" +``` +::: +:::: + +Make sure to rerun your PHP application. + + +## Resources + +To learn how to enable debug logging for the EDOT Collector, refer to [Enable debug logging for EDOT Collector](../edot-collector/enable-debug-logging.md). diff --git a/troubleshoot/ingest/opentelemetry/toc.yml b/troubleshoot/ingest/opentelemetry/toc.yml index c6b252b8c2..7cee5d7992 100644 --- a/troubleshoot/ingest/opentelemetry/toc.yml +++ b/troubleshoot/ingest/opentelemetry/toc.yml @@ -19,5 +19,6 @@ toc: - file: edot-sdks/nodejs/index.md - file: edot-sdks/php/index.md - file: edot-sdks/python/index.md + - file: edot-sdks/enable-debug-logging.md - file: no-data-in-kibana.md - file: contact-support.md From 240e7ee0faeaa94311f6bccecf3389232e8fd114 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Wed, 27 Aug 2025 20:13:11 +0200 Subject: [PATCH 2/5] Apply comments --- .../edot-sdks/enable-debug-logging.md | 40 ++++++++++++------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md index 9e38d58cb9..9298562de9 100644 --- a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md +++ b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md @@ -45,7 +45,7 @@ You can enable debug logging using environment variables. For general EDOT Java agent debugging, try: ```bash -export OTEL_JAVAAGENT_LOG_LEVEL=debug +export ELASTIC_OTEL_JAVAAGENT_LOG_LEVEL=debug java -jar your-app.jar ``` The output is captured span information from the agent itself, in a JSON format. @@ -126,27 +126,37 @@ node your-app.js ## PHP -Set this environment variable: +Elastic’s PHP agent doesn't use the standard `OTEL_LOG_LEVEL` variable. Instead, enable debug-level logging with the agent’s own configuration options: `ELASTIC_OTEL_LOG_LEVEL_FILE`, `ELASTIC_OTEL_LOG_LEVEL_STDERR`, or `ELASTIC_OTEL_LOG_LEVEL_SYSLOG`. Refer to [Logging configuration](opentelemetry://reference/edot-sdks/php/configuration.md#logging-configuration) for more details. -::::{tab-set} - -:::{tab-item} macOS +For deeper troubleshooting, you can also enable diagnostic data collection. For example: ```bash -export OTEL_LOG_LEVEL=debug -php your-application.php +export ELASTIC_OTEL_DEBUG_DIAGNOSTIC_FILE=/tmp/php_diag_%p_%t.txt php test.php ``` -::: -:::{tab-item} Windows +Ensure the file path is writable by the PHP process. If multiple PHP processes are running, use directives in the diagnostic file name to generate unique files and prevent overwriting. You can use: -```powershell -$env:OTEL_LOG_LEVEL="debug" -``` -::: -:::: +* `%p` to insert the process ID + +* `%t` to insert the UNIX timestamp + +After setting the variable, restart the PHP process you're collecting diagnostics for, then send an HTTP request or run a script (for PHP-CLI). + +The collected information includes: + +* Process ID and parent process ID + +* User ID of the worker process + +* Loaded PHP extensions + +* Output from the `phpinfo()` function + +* Memory usage and maps `(/proc/{{id}}/maps` and `/proc/{{id}}/smaps_rollup)` + +* Process status `(/proc/{{id}}/status)` -Make sure to rerun your PHP application. +Disable diagnostic collection when you're done by unsetting the variable or restoring the previous configuration. ## Resources From 9db9b6ba29e2452411c800cf0c6e94ac4002611b Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Thu, 28 Aug 2025 19:08:23 +0200 Subject: [PATCH 3/5] Comments --- .../opentelemetry/edot-sdks/enable-debug-logging.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md index 9298562de9..096cadb9d0 100644 --- a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md +++ b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md @@ -123,10 +123,19 @@ node your-app.js ::: :::: +This produces debug-level logs from the SDK itself. + +If you also want to inspect the actual telemetry your app is generating, configure exporters to log traces, metrics, or logs to the console. For example: ## PHP -Elastic’s PHP agent doesn't use the standard `OTEL_LOG_LEVEL` variable. Instead, enable debug-level logging with the agent’s own configuration options: `ELASTIC_OTEL_LOG_LEVEL_FILE`, `ELASTIC_OTEL_LOG_LEVEL_STDERR`, or `ELASTIC_OTEL_LOG_LEVEL_SYSLOG`. Refer to [Logging configuration](opentelemetry://reference/edot-sdks/php/configuration.md#logging-configuration) for more details. +While the EDOT PHP agent supports the standard `OTEL_LOG_LEVEL` variable, you must also configure at least one of the Elastic-specific sink options to direct logs to a destination: + +* `ELASTIC_OTEL_LOG_LEVEL_FILE` +* `ELASTIC_OTEL_LOG_LEVEL_STDERR` +* `ELASTIC_OTEL_LOG_LEVEL_SYSLOG` + +Refer to [Logging configuration](opentelemetry://reference/edot-sdks/php/configuration.md#logging-configuration) for more details. For deeper troubleshooting, you can also enable diagnostic data collection. For example: From 924cf0dcd610ec965f25f91e7da41d0741a8198c Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Fri, 29 Aug 2025 11:38:59 +0200 Subject: [PATCH 4/5] Add code snippet --- .../ingest/opentelemetry/edot-sdks/enable-debug-logging.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md index 096cadb9d0..d2bc5ec290 100644 --- a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md +++ b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md @@ -127,6 +127,12 @@ This produces debug-level logs from the SDK itself. If you also want to inspect the actual telemetry your app is generating, configure exporters to log traces, metrics, or logs to the console. For example: +```sh +export OTEL_TRACES_EXPORTER=otlp, console +export OTEL_METRICS_EXPORTER=otlp, console +node --import @elastic/opentelemetry-node your-app.js +``` + ## PHP While the EDOT PHP agent supports the standard `OTEL_LOG_LEVEL` variable, you must also configure at least one of the Elastic-specific sink options to direct logs to a destination: From e9d2e04c19e6d860096107eb12f5cd4a8e1f8a17 Mon Sep 17 00:00:00 2001 From: Aleksandra Spilkowska Date: Mon, 1 Sep 2025 17:15:35 +0200 Subject: [PATCH 5/5] Update code snippets --- .../ingest/opentelemetry/edot-sdks/enable-debug-logging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md index d2bc5ec290..02aa946cbf 100644 --- a/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md +++ b/troubleshoot/ingest/opentelemetry/edot-sdks/enable-debug-logging.md @@ -110,7 +110,7 @@ Set this environment variable before starting your app: ```bash export OTEL_LOG_LEVEL=debug -node your-app.js +node --import @elastic/opentelemetry-node your-app.js ``` ::: @@ -118,7 +118,7 @@ node your-app.js ```powershell $env:OTEL_LOG_LEVEL="debug" -node your-app.js +node --import @elastic/opentelemetry-node your-app.js ``` ::: ::::