Every telemetry system needs settings. The question is where those settings should live.

What needs to be configured

When an application produces traces, metrics, and logs, many decisions must be made. What is this service called? Where should the data be sent? Should every request be traced, or only a fraction? Which format should be used to pass trace identity to other services? How large can the internal buffers be? Each of these answers can differ from one environment to another.

A service running on a developer’s laptop may print telemetry to the console. The same service in a test environment may send everything to a small test backend. In production, it may sample only a small fraction of traces and send them to a central Collector with secure credentials. The code is identical in all three places, but the settings are different.

Why hard-coding settings is a bad idea

If these settings were written inside the source code, every change would need a code edit, a rebuild, and a new release. Teams would end up with different builds for different environments, which makes testing unreliable. Secrets such as access keys would be stored in source files and might leak. And if a service is built from a third-party product that you cannot edit, you would have no way to configure it at all.

Before meeting the variables, it helps to list the decisions they control.

The idea of defaults

For nearly every setting, OpenTelemetry defines a sensible default. If you set nothing, the SDK uses those defaults. For example, a typical default is to send data using the OpenTelemetry Protocol to a local address. This is why a quick demo often works with almost no configuration, and why production setups then override only the values that must differ.

A plain definition first, then the two families you will meet in practice.

The definition

An environment variable is a named value that the operating system, a container platform, or a launcher script passes to a program when it starts. The program can read these values while it runs. The OTEL_* environment variables are those whose names start with the prefix OTEL_, and which OpenTelemetry defines as the standard way to configure its SDKs and instrumentation from the outside.

Why a shared prefix matters

The prefix tells everyone, humans and tools alike, that a variable belongs to OpenTelemetry. It prevents clashes with variables used by other software, and it makes the settings easy to find with a simple search of a deployment file. Most importantly, the names are specified in a language-neutral document. A service written in Java, one in Python, and one in JavaScript can all be configured with the same variable names, which greatly simplifies platform operations.

Two families of variables

A little understanding of the mechanics prevents many beginner mistakes.

Where variables come from

Environment variables are set before a program starts and are inherited by the program from whatever launched it. On a laptop, that may be a terminal session or a script. In a container platform, they are usually declared in the deployment description, so every copy of the container starts with the same values. In managed cloud services, there is normally a settings page where you enter names and values.

They are read at startup

Most SDKs read these variables once, when the SDK is created. Changing a variable while the program is running usually has no effect until the program is restarted. This is why configuration changes are normally rolled out by restarting or redeploying the service.

Everything is text

An environment variable is always a piece of text. The SDK is responsible for converting it into the type that the setting needs. The specification defines clear rules for this conversion so that every SDK behaves consistently.

What happens when a value is wrong

The specification asks SDKs to be forgiving. If a value cannot be understood, the SDK should report a warning through its own internal logging and then ignore the bad value, using the default instead. It should not crash your application because of a typing mistake in a setting. The cost of this friendliness is that a typo can silently leave you with the default behavior, so it is wise to look for warnings during testing.

If you set only two things, make them the service name and its descriptive labels.

OTEL_SERVICE_NAME

This variable sets the logical name of your service, such as “checkout” or “inventory.” The name appears on every trace, metric, and log produced by the service, and it is the main way tools group and display data. Without it, SDKs fall back to an unhelpful default, which makes data from different services indistinguishable.

OTEL_RESOURCE_ATTRIBUTES

This variable carries extra descriptive labels for the service, written as a comma-separated list of name-and-value pairs. Common labels include the service version, the deployment environment such as production or staging, the owning team, and the cloud region. These labels are called resource attributes because they describe the resource that produces the telemetry.

How the two interact

The service name can also be written inside the resource attributes list. If both are present, the dedicated service name variable takes precedence. This lets operators override the name easily without editing a long list of attributes.

Special characters in values

Because the list uses commas and equals signs as separators, values that contain those characters need to be encoded, using the percent-encoding rules described in the specification. This is an easy place for subtle mistakes, especially when values are built automatically by scripts or platform templates.

The largest family of OTEL_* variables controls how telemetry leaves your application.

The OTLP exporter family

OTLP, the OpenTelemetry Protocol, is the standard way of sending telemetry. Its settings all begin with OTEL_EXPORTER_OTLP. They control the address, the transport protocol, the credentials, the compression, and the waiting time.

General versus signal-specific

Most exporter variables exist in two forms. The general form applies to all signals, and a signal-specific form applies only to traces, only to metrics, or only to logs. When both are set, the more specific one wins for its signal. This lets you send traces to one place and metrics to another, while keeping the shared settings, such as credentials, in one variable.

flowchart TD
    START["Exporter needs a setting for traces"] --> Q1{"Is the traces specific variable set?"}
    Q1 -- "Yes" --> USE1["Use the traces specific value"]
    Q1 -- "No" --> Q2{"Is the general OTLP variable set?"}
    Q2 -- "Yes" --> USE2["Use the general value"]
    Q2 -- "No" --> USE3["Use the built in default"]
        

A subtle detail about endpoint addresses

For HTTP-based transport, the general endpoint variable is treated as a base address, and the SDK appends a standard path for each signal, such as one for traces, one for metrics, and one for logs. A signal-specific endpoint variable, however, is used exactly as written, with no path added. This difference surprises many people, and it is a common reason that data arrives at the wrong path of a receiver.

Besides configuring the exporter, you can choose which exporter each signal uses, or turn export off.

The three selection variables

Three variables pick the exporter for each signal: one for traces, one for metrics, and one for logs. Each accepts a choice such as OTLP, a console output for debugging, or none to switch that signal’s export off. Some signals support additional choices, for instance a pull-based format for metrics that monitoring tools can scrape, or an older tracing format that some systems still use.

Using none and console wisely

The none choice is helpful when you want traces but not metrics, or when you want to test an application without producing any outbound traffic. The console choice is helpful during development, because telemetry appears right in the terminal where you can read it. Neither is intended for production use in most cases, since console output is hard to analyze and none discards data.

Multiple exporters

Some SDKs accept a list, such as sending to the Collector and also printing to the console at the same time. Support for lists varies by language, so test the behavior in your environment before relying on it.

Two small groups of variables shape how many traces you keep and how trace identity travels between services.

Sampling

Sampling is the practice of keeping only a portion of traces to control cost. The sampler variable chooses the strategy by name, and a companion argument variable supplies a value for strategies that need one, such as a ratio.

Why parent-based is the usual default

If every service made its own random decision, you would get traces that are recorded in one service and missing in the next. A parent-based sampler respects the choice made at the start of the request, so either the whole trace is kept or none of it. Many SDKs default to a parent-based sampler that keeps traces when the parent says so, and keeps new traces when there is no parent.

Propagators

The propagators variable lists the formats used to pass trace identity and baggage between services. The common default combines the W3C Trace Context standard with W3C Baggage. Other choices include older formats still used by some systems. All services in a call chain must share at least one format, or traces will break at the boundary.

Another group of variables tunes how much memory and time the SDK may use, and how often it sends data.

Batch processors

SDKs do not send every span or log the moment it finishes. Instead, a batch processor collects them in a queue and sends them in groups. Variables with the prefixes OTEL_BSP for spans and OTEL_BLRP for log records control the batching behavior.

Size limits on telemetry

Other variables limit how large individual pieces of telemetry may grow. They cap the number of attributes per span, the number of events and links, and the length of attribute values. These limits protect the application from runaway memory use when some code attaches huge values, and they protect backends from oversized records.

Metric collection timing

Metrics are sent on a regular rhythm. A variable sets the interval between exports, and another sets the timeout for one export attempt. Variables for OTLP metrics also let you choose how counts are reported over time, such as cumulative totals versus changes since the last report, and how histograms are aggregated. These choices must match what your backend expects.

Beyond the shared standard, each ecosystem adds its own settings for features unique to it.

Why language-specific variables exist

Some behavior only makes sense in one environment. A Java agent needs to be switched on or off and pointed at extra configuration. A Python launcher needs a way to disable particular instrumentations or to turn on log correlation. A .NET agent needs paths to its runtime components. These settings are not part of the common specification, so each project defines them, usually with an extra segment in the name that identifies the language or tool.

Other cross-cutting variables

A few variables apply across languages but are specialized. One lets you disable the entire SDK, which is useful as an emergency off switch. One controls the verbosity of the SDK’s own internal messages. One manages the transition between older and newer naming conventions for attributes, allowing teams to opt in to the new names gradually. Newer parts of the specification also describe a way to point to a configuration file, as an alternative to many separate variables. Check the current status of that feature for your language.

The same setting may be given in several places. Knowing which one wins prevents confusing surprises.

The layers of configuration

A setting can come from several layers. At the bottom are the built-in defaults of the SDK. Above them are environment variables. Above those, in many setups, are values set explicitly in code, or in a configuration file, or through startup options of an agent. In general, the more explicit and closer to the program the setting is, the more likely it is to override a broader or more generic one. However, the exact rules differ between languages and tools, so confirm them in the documentation.

flowchart TD
    D["Built in defaults"] --> E["Environment variables"]
    E --> C["Configuration file or agent options, where supported"]
    C --> P["Values set explicitly in code"]
    P --> F["Final effective setting"]
        

Within environment variables

Inside the family of environment variables themselves, two precedence rules are worth remembering. A signal-specific variable overrides the general one for that signal. And a dedicated variable overrides an equivalent value tucked inside a list, as with the service name versus the resource attributes list.

Let us see how these variables are used when a service is deployed to a cluster.

The scenario

A team runs a checkout service as several copies in a Kubernetes cluster. They want each copy to report under the name “checkout,” label its version and environment, send data to a Collector running on the same node, sample a tenth of new traces, and use the standard context format.

sequenceDiagram
    participant D as Deployment Description
    participant K as Kubernetes
    participant C as Container
    participant S as SDK or Agent
    participant O as Collector
    D->>K: List of OTEL variables and values
    K->>C: Start container with variables set
    C->>S: Application starts, SDK initializes
    S->>S: Read variables, convert, apply over defaults
    S->>O: Send telemetry with configured identity
    Note over S,O: Change a value, redeploy, and the cycle repeats
        

Environment variables are convenient, but they are not a safe vault. Some of them carry sensitive values.

Which variables may hold secrets

The headers variable for the OTLP exporter often contains an API key or a token for a hosted backend. Variables that point to private keys or certificates also deserve care. Even the resource attributes may reveal internal names or topology that you may not want to expose widely.

Where environment variables can leak

Safer habits

Store secrets in the secret management feature of your platform and inject them into the environment only at runtime, instead of writing them in plain deployment files. Give each service the narrowest credentials possible, so a leak has a limited effect. Rotate keys periodically. Another approach is to send data to a local Collector without credentials, and let the Collector hold the backend secrets, so applications never see them.

The environment variable approach is popular for good reasons, but it has real limits.

Where the limits show up

When telemetry looks wrong, the cause is very often a setting. Here is a field guide.

Troubleshooting guide

Habits that work

Traps to avoid

Quick answers to the questions people ask most often.

Not to get started, because defaults exist. But in practice you should always set the service name, and usually the exporter endpoint and the protocol, so your data is labeled and delivered correctly.

The specification-defined variables are meant to be the same across languages that support them. Language-specific variables, such as those for agents and launchers, differ by ecosystem. Always check the documentation for your language and version.

Usually not. Most SDKs read variables once at startup, so changes take effect after a restart. For live changes, consider mechanisms such as remote-controlled samplers or processing in a Collector.

The SDK is supposed to log a warning and use the default value instead. That means your application keeps running, but with the default behavior, so you should check startup messages when testing new settings.

Because only the word true, in any letter case, is read as true. Values such as yes, on, or one are read as false. Use the exact word true.

The general variables apply to all signals. The signal-specific ones apply only to traces, metrics, or logs, and they override the general ones for that signal. For HTTP endpoints, the general one is a base address, while the specific one is used exactly as written.

Mostly no. The Collector is configured by its own file, which has its own way to insert environment values. The OTEL_* variables described here mainly configure SDKs and instrumentation inside applications.

Often the setting in code takes precedence, because it is more explicit, but the exact behavior depends on the language and the tool. Avoid defining the same setting in both places to prevent confusion.

It is common, but treat it as a secret. Inject it through your platform’s secret management, limit who can view the environment, and rotate it regularly. Alternatively, let a Collector hold the credentials.

The project is developing a declarative configuration approach, where a file describes the full setup. Support and maturity vary by language, so check the current status before adopting it.

The OTEL_* environment variables are OpenTelemetry’s standard remote control. They let operators and developers set a service’s name and labels, choose exporters and their addresses, select sampling and propagation behavior, tune batching and limits, and enable or disable features, all without changing source code. Their names are shared across languages, their values are plain text that SDKs convert using clear rules, and invalid values quietly fall back to defaults. Specific settings override general ones, and explicit code often overrides environment values, so it is wise to decide where each setting lives. Language-specific variables extend the standard for particular agents. Used with care for secrets, consistency across the fleet, and attention to startup warnings, they make telemetry configuration simple, repeatable, and portable.