Instrumenting Applications Using OpenTelemetry

Principles

• Zero-code auto-instrumentation and code-based auto-instrumentation are the go-to options. Both approaches capture HTTP, database, and framework-internal spans automatically without modifying application code and may be used interchangeably depending on the use case, language, and frameworks involved.
• A combination of framework-native OTel and the auto-instrumentation meta-package/agent is acceptable when they complement each other, but verify they don't produce duplicate spans for the same request.
• Manual instrumentation should never be used. Do not add tracer.startSpan() calls or similar manual instrumentation to the application.
• When a framework provides its own OTel integration, prefer it over the external agent unless the language section says otherwise.
• Always use latest versions of auto-instrumentation libraries for the most stable experience.

Workflow

1. Clarify the service name

Ask the developer what they want to call the service (service.name). Suggest names based on the repository, directory, or module name.

2. Discover the application

Run the discovery reference to scan the target directory. If the repository contains multiple runnable services, present the candidate list and ask the developer to choose the target app or directory before continuing.