Skip to content

Troubleshooting

Work through these checks in order:

  1. Confirm the agent version: inspect the Java JAR name, or run beacon --version, npm ls @beacon-observability/nodejs, beacon-dotnet version, or vendor/bin/beacon-php --version.
  2. Confirm OTEL_SERVICE_NAME, endpoint, and protocol in the same process environment that starts the application.
  3. Test network access from the application host to the receiver port.
  4. Generate traffic through a supported framework or library; startup alone may not create a span.
  5. Enable diagnostics for the language below, reproduce the issue, save the output, and restore the normal configuration.

Debugging and diagnostics by language

Debugging entry points differ by language. Each language page includes commands, output locations, and cleanup steps.

Language Debugging or diagnostic entry point Output
Java OTEL_JAVAAGENT_DEBUG=true or -Dotel.javaagent.debug=true Agent debug logs
Python Configure the opentelemetry logger through application logging; use OTEL_TRACES_EXPORTER=otlp,console for an initial check SDK logging depends on Python logging configuration; console Spans verify telemetry creation
Node.js OTEL_LOG_LEVEL=debug, retaining the existing preload Console diagnostics
.NET OTEL_LOG_LEVEL=debug with OTEL_DOTNET_AUTO_LOG_DIRECTORY Instrumentation log files; beacon-dotnet status checks installation status
PHP OTEL_LOG_LEVEL=debug, OTEL_PHP_LOG_DESTINATION=stderr; vendor/bin/beacon-php doctor --json SDK internal logs and a runtime diagnostic report

Agent diagnostic logging is configured separately from telemetry log export controlled by OTEL_LOGS_EXPORTER. Retain the service name, OTLP endpoint, and loading method, enable diagnostics temporarily, reproduce once, then restore the normal launch configuration. Remove credentials and sensitive request contents before sharing logs.

Profiles are missing

  • Java: check that the runtime is JDK 11 or later and that the profile directory is writable.
  • Python and Node.js: verify OTEL_PROFILING_ENABLED=true, the upload URL, and that the process lives longer than the export interval.
  • Do not send a profile payload to an OTLP traces endpoint; Java uses JFR multipart uploads; Python and Node.js use pprof multipart uploads. Enable the DataKit Profile input for either format.

Security data is missing

  • Confirm BEACON_SECURITY_ENABLED=true and an OTLP Logs exporter in the application process environment.
  • Python needs BEACON_SECURITY_PYTHON_INCLUDE with application module prefixes. Node.js needs BEACON_SECURITY_NODE_INCLUDE with application source roots and must use the ESM --import preload.
  • Runtime SBOM can be emitted before findings. Generate a request that crosses a modeled source and sink; findings are not generated by startup alone.
  • Local diagnostic files stay disabled unless BEACON_SECURITY_LOCAL_OUTPUT_ENABLED=true. Their absence does not mean OTLP Logs export failed.

If the application fails only when the agent is active, disable the agent first to restore service, preserve the agent debug log, runtime version, command line with secrets removed, and the smallest reproducible request.

DataKit endpoint or protocol mismatch

  • Use http://<DataKit-IP>:4317 for OTLP/gRPC, without HTTP paths.
  • For OTLP/HTTP, use http/protobuf and the shared endpoint http://<DataKit-IP>:9529/otel. Signal-specific endpoints must include /otel/v1/traces, /otel/v1/metrics, or /otel/v1/logs.
  • curl http://<DataKit-IP>:9529/v1/ping only checks the DataKit HTTP service; it does not verify the gRPC port or input configuration.
  • Check listening addresses and network policies for remote access. Within a container, 127.0.0.1 refers to that container.

See Common configuration for setup and verification.

Configuration references

Feedback

Is this page helpful?