{"id":28662574,"url":"https://github.com/open-telemetry/opentelemetry-injector","last_synced_at":"2026-01-12T15:30:17.851Z","repository":{"id":296429603,"uuid":"992848328","full_name":"open-telemetry/opentelemetry-injector","owner":"open-telemetry","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-11T16:23:50.000Z","size":30,"stargazers_count":12,"open_issues_count":9,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-13T00:08:18.542Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-telemetry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-29T20:07:21.000Z","updated_at":"2025-06-11T16:23:55.000Z","dependencies_parsed_at":"2025-05-31T00:21:47.004Z","dependency_job_id":"f0aec262-faec-4598-827a-59f60dbb146c","html_url":"https://github.com/open-telemetry/opentelemetry-injector","commit_stats":null,"previous_names":["open-telemetry/opentelemetry-injector"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/open-telemetry/opentelemetry-injector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-injector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-injector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-injector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-injector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-telemetry","download_url":"https://codeload.github.com/open-telemetry/opentelemetry-injector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-injector/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259634408,"owners_count":22887701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-13T11:09:26.694Z","updated_at":"2026-01-12T15:30:17.832Z","avatar_url":"https://github.com/open-telemetry.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"## OpenTelemetry Injector\n\nThe OpenTelemetry injector is a shared library (written in [Zig](https://ziglang.org/)) that is intended to be\nused via the environment variable [`LD_PRELOAD`](https://man7.org/linux/man-pages/man8/ld.so.8.html#ENVIRONMENT), the\n[`/etc/ld.so.preload`](https://man7.org/linux/man-pages/man8/ld.so.8.html#FILES) file, or similar mechanisms to inject\nenvironment variables into processes at startup.\n\nIt serves two main purposes:\n* Inject an OpenTelemetry auto-instrumentation agent into the process to capture and report distributed traces and\n  metrics to the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) for supported runtimes.\n* Set resource attributes automatically (for example Kubernetes related resource attributes and service related\n  resource attributes in environments where this is applicable).\n\nThe injector can be used to enable automatic zero-touch instrumentation of processes.\nFor this to work, the injector binary needs to be bundled together with the OpenTelemetry auto-instrumentation agents\nfor the target runtimes.\n\nOfficial RPM and DEB packages that contain the injector as well as the auto-instrumentation agents are available, and\ncan be downloaded from the [releases page](https://github.com/open-telemetry/opentelemetry-injector/releases).\nThe OpenTelemetry injector Debian/RPM packages install the OpenTelemetry auto-instrumentation agents, the\n`libotelinject.so` shared object library, and a default configuration file to automatically instrument applications and\nservices to capture and report distributed traces and metrics to the\n[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/).\n\nThe `opentelemetry-injector` deb/rpm package installs and supports configuration of the following auto-instrumentation\nagents:\n\n- [Java](https://opentelemetry.io/docs/zero-code/java/)\n- [Node.js](https://opentelemetry.io/docs/zero-code/js/)\n- [.NET](https://opentelemetry.io/docs/zero-code/dotnet/)\n\n## Activation and Configuration\n\nThis method requires `root` privileges.\n\n1. Add the path of the provided `/usr/lib/opentelemetry/libotelinject.so` shared object library to the\n   [`/etc/ld.so.preload`](https://man7.org/linux/man-pages/man8/ld.so.8.html#FILES) file to activate auto-\n   instrumentation for ***all*** supported processes on the system. For example:\n   ```\n   echo /usr/lib/opentelemetry/libotelinject.so \u003e\u003e /etc/ld.so.preload\n   ```\n   Alternatively, set the environment variable `LD_PRELOAD=/usr/lib/opentelemetry/libotelinject.so` for a specific\n   process to activate auto-instrumentation for that process. For example:\n   ```\n   LD_PRELOAD=/usr/lib/opentelemetry/libotelinject.so node myapp.js\n   ```\n2. The default configuration file `/etc/opentelemetry/otelinject.conf` includes the required settings, i.e. the paths to\n   the respective auto-instrumentation agents per runtime:\n   ```\n   dotnet_auto_instrumentation_agent_path_prefix=/usr/lib/opentelemetry/dotnet\n   jvm_auto_instrumentation_agent_path=/usr/lib/opentelemetry/javaagent.jar\n   nodejs_auto_instrumentation_agent_path=/usr/lib/opentelemetry/otel-js/node_modules/@opentelemetry-js/otel/instrument\n   ```\n\n   You can override the location of the configuration file by setting `OTEL_INJECTOR_CONFIG_FILE`.\n\n   You may want to modify this file for a couple of reasons:\n   - You want to provide your own instrumentation files.\n\n   - You want to selectively disable auto-instrumentation for a specific runtime, by setting the respective path\n     to an empty string in the configuration file.\n     For example, the following file would leave JVM and Node.js auto-instrumentation active, while disabling .NET\n     auto-instrumentation:\n      ```\n      dotnet_auto_instrumentation_agent_path_prefix=\n      jvm_auto_instrumentation_agent_path=/usr/lib/opentelemetry/javaagent.jar\n      nodejs_auto_instrumentation_agent_path=/usr/lib/opentelemetry/otel-js/node_modules/@opentelemetry-js/otel/instrument\n      ```\n   - You want to selectively enable (or disable) auto-instrumentation for a subset of programs (services) on your system.\n     For example, you may want to only enable instrumentation of services that match a specific executable path pattern, or\n     to programs that do not contain certain arguments on the command line.\n     See [details on configuring the program inclusion and exclusion criteria](#details-on-configuring-the-program-inclusion-and-exclusion-criteria) for more information.\n\n   The values set in the configuration file can be overridden with environment variables.\n   (This should usually not be necessary.)\n   - `DOTNET_AUTO_INSTRUMENTATION_AGENT_PATH_PREFIX`: the path to the directory containing the .NET auto-instrumentation\n     agent files\n   - `JVM_AUTO_INSTRUMENTATION_AGENT_PATH`: the path to the Java auto-instrumentation agent JAR file\n   - `NODEJS_AUTO_INSTRUMENTATION_AGENT_PATH`: the path to the Node.js auto-instrumentation agent registration file\n   - `OTEL_INJECTOR_INCLUDE_PATHS`: a comma-separated list of glob patterns to match executable paths\n   - `OTEL_INJECTOR_EXCLUDE_PATHS`: a comma-separated list of glob patterns to exclude executable paths\n   - `OTEL_INJECTOR_INCLUDE_WITH_ARGUMENTS`: a comma-separated list of glob patterns to match process arguments\n   - `OTEL_INJECTOR_EXCLUDE_WITH_ARGUMENTS`: a comma-separated list of glob patterns to exclude process arguments\n\n   These aforementioned environment variables can also be used to selectively disable auto-instrumentation for a\n   specific runtime, by setting the respective variable to an empty string, that is, set:\n    - `DOTNET_AUTO_INSTRUMENTATION_AGENT_PATH_PREFIX=\"\"` to disable .NET auto-instrumentation\n    - `JVM_AUTO_INSTRUMENTATION_AGENT_PATH=\"\"` to disable JVM auto-instrumentation\n    - `NODEJS_AUTO_INSTRUMENTATION_AGENT_PATH=\"\"` to disable Node.js auto-instrumentation\n\n3. (Optional) The default env agent configuration file `/etc/opentelemetry/default_auto_instrumentation_env.conf` is empty (use\n   `all_auto_instrumentation_agents_env_path` option to specify other path). Environment variables added to this file\n   will be passed to all agents' environments. **NOTE**: environment variables which do not start with `OTEL_` are\n   ignored.\n\n   The `auto_instrumentation_env.conf` file format is the same as other configurations:\n\n   ```\n   OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317\n   OTEL_PROPAGATORS=tracecontext,baggage\n   ```\n\n4. Reboot the system or restart the applications/services for any changes to take effect. The `libotelinject.so` shared\n   object library will then be preloaded for all subsequent processes and inject the environment variables from the\n   `/etc/opentelemetry/otelinject` configuration files for Java and Node.js processes.\n\nWhen providing your own instrumentation files (for example via environment variables like `DOTNET_AUTO_INSTRUMENTATION_AGENT_PATH_PREFIX`) the following directory structure is expected:\n- `JVM_AUTO_INSTRUMENTATION_AGENT_PATH`: This path must point to the Java auto-instrumentation agent JAR file `opentelemetry-javaagent.jar`.\n- `NODEJS_AUTO_INSTRUMENTATION_AGENT_PATH`: The path to an installation of the npm module `@opentelemetry/auto-instrumentations-node`.\n- `DOTNET_AUTO_INSTRUMENTATION_AGENT_PATH_PREFIX`: this path must be a directory that contains the following\n  subdirectories and files:\n   - For `x86_64` systems using `glibc`:\n      - `glibc/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so`\n      - `glibc/AdditionalDeps`\n      - `glibc/store`\n      - `glibc/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll`\n   - For `x86_64` systems using `musl`:\n       - `musl/linux-musl-x64/OpenTelemetry.AutoInstrumentation.Native.so`\n       - `musl/AdditionalDeps`\n       - `musl/store`\n       - `musl/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll`\n   - For `arm64` systems using `glibc`:\n       - `glibc/linux-arm64/OpenTelemetry.AutoInstrumentation.Native.so`\n       - `glibc/AdditionalDeps`\n       - `glibc/store`\n       - `glibc/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll`\n   - For `arm` systems using `musl`:\n       - `musl/linux-musl-arm64/OpenTelemetry.AutoInstrumentation.Native.so`\n       - `musl/AdditionalDeps`\n       - `musl/store`\n       - `musl/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll`\n\nNote that the defaults provided by the RPM and Debian packages take care of all of that, and it is not necessary to\nedit `/etc/opentelemetry/otelinject.conf` or set any of the above environment variables.\n\nCheck the following for details about the auto-instrumtation agents and further configuration options:\n- [Java](https://opentelemetry.io/docs/zero-code/java/agent/configuration/)\n- [Node.js](https://opentelemetry.io/docs/zero-code/js/configuration/)\n- [.NET](https://opentelemetry.io/docs/zero-code/dotnet/configuration/)\n\n### Environment Modifications\n\nHere is an overview of the modifications that the injector will apply:\n\n* It sets (or appends to) `NODE_OPTIONS` to activate the Node.js instrumentation agent.\n* It adds a `-javaagent` flag to `JAVA_TOOL_OPTIONS` to activate the Java OTel SDK.\n* It sets the required environment variables for activating the OpenTelemetry SDK for .NET:\n    * `CORECLR_ENABLE_PROFILING`\n    * `CORECLR_PROFILER`\n    * `CORECLR_PROFILER_PATH`\n    * `DOTNET_ADDITIONAL_DEPS`\n    * `DOTNET_SHARED_STORE`\n    * `DOTNET_STARTUP_HOOKS`\n    * `OTEL_DOTNET_AUTO_HOME`\n    * Note that the injector will not append to existing environment variables but overwrite them unconditionally if\n      they are already set.\n      In contrast to other runtimes, .NET does not support adding multiple agents.\n* It inspects specific existing environment variables and populates `OTEL_RESOURCE_ATTRIBUTES` with additional resource\n  attributes. These environment variables need to be set externally (for example by a Kubernetes operator with a mutating\n  webhook on the pod spec template of the workload). If `OTEL_RESOURCE_ATTRIBUTES` is already set, the additional\n  key-value pairs are appended to the existing value of `OTEL_RESOURCE_ATTRIBUTES`. Existing key-value pairs are not\n  overwritten, that is if e.g. `OTEL_RESOURCE_ATTRIBUTES` already has a key-value pair for `k8s.pod.name`, the existing\n  key-value pair takes priority.\n  The following environment variables and resource attributes are supported:\n    * `OTEL_INJECTOR_RESOURCE_ATTRIBUTES` is expected to contain key-value pairs\n      (e.g. `my.resource.attribute=value,my.other.resource.attribute=another-value`) and will be added as-is.\n    * `OTEL_INJECTOR_SERVICE_NAME` will be translated to `service.name`\n    * `OTEL_INJECTOR_SERVICE_VERSION` will be translated to `service.version`\n    * `OTEL_INJECTOR_SERVICE_NAMESPACE` will be translated to `service.namespace`\n    * `OTEL_INJECTOR_K8S_NAMESPACE_NAME` will be translated to `k8s.namespace.name`\n    * `OTEL_INJECTOR_K8S_POD_NAME` will be translated to `k8s.pod.name`\n    * `OTEL_INJECTOR_K8S_POD_UID` will be translated to `k8s.pod.uid`\n    * `OTEL_INJECTOR_K8S_CONTAINER_NAME` will be translated to `k8s.container.name`\n\n#### Mapping Kubernetes Resource Attributes\n\nWhile you can set all resource attributes with `OTEL_INJECTOR_RESOURCE_ATTRIBUTES`, the additional environment\nvariables controlling individual resource attributes (like `OTEL_INJECTOR_SERVICE_NAME` or\n`OTEL_INJECTOR_K8S_NAMESPACE_NAME`) are useful in Kubernetes for deriving resource attributes via\n[field selectors](https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#use-pod-fields-as-values-for-environment-variables),\ne.g. by adding a snippet like this to the pod spec template:\n```\n- name: OTEL_INJECTOR_SERVICE_NAME\n  valueFrom:\n    fieldRef:\n      fieldPath: metadata.labels['app.kubernetes.io/name']\n```\n\nThe following provides an overview of the intended mappings:\n\n| Environment Variable               | Intended Mapping |\n| ---------------------------------- | ---------------- |\n| `OTEL_INJECTOR_K8S_NAMESPACE_NAME` | `valueFrom.fieldRef.fieldPath: metadata.namespace` |\n| `OTEL_INJECTOR_K8S_POD_NAME`       | `valueFrom.fieldRef.fieldPath: metadata.name` |\n| `OTEL_INJECTOR_K8S_POD_UID`        | `valueFrom.fieldRef.fieldPath: metadata.uid` |\n| `OTEL_INJECTOR_K8S_CONTAINER_NAME` | The container's name (no field selector) |\n| `OTEL_INJECTOR_SERVICE_NAME`       | `valueFrom.fieldRef.fieldPath: metadata.labels['app.kubernetes.io/name']` |\n| `OTEL_INJECTOR_SERVICE_VERSION`    | `valueFrom.fieldRef.fieldPath: metadata.labels['app.kubernetes.io/version']` |\n| `OTEL_INJECTOR_SERVICE_NAMESPACE`  | `valueFrom.fieldRef.fieldPath: metadata.labels['app.kubernetes.io/part-of']` |\n\nThe environment variable `OTEL_INJECTOR_RESOURCE_ATTRIBUTES` can be set to key-value pairs derived from the\nannotations `resource.opentelemetry.io/*`, to support mapping annotations like\n`resource.opentelemetry.io/service.namespace`, `resource.opentelemetry.io/service.name` to their respective resource\nattributes.\n\nSee also:\n* https://opentelemetry.io/docs/specs/semconv/resource/k8s/\n* https://opentelemetry.io/docs/specs/semconv/non-normative/k8s-attributes/\n* https://kubernetes.io/docs/tasks/inject-data-application/environment-variable-expose-pod-information/#use-pod-fields-as-values-for-environment-variables\n\n### Configure the Injector's Logging\n\nBy default, the injector only logs errors.\nSet the environment variable `OTEL_INJECTOR_LOG_LEVEL` to change the log level.\nValid values are:\n- `debug`\n- `info`\n- `warn`\n- `error` - this is the default value\n- `none` - suppress all log output from the injector; this is useful for scenarios where you pipe `stderr` into another\n  process and parse it.\n\nThe injector's log message will be written to `stderr` of the process that is being instrumented.\n\n### Details on configuring the program inclusion and exclusion criteria\n\nIf you want to selectively enable (or disable) auto-instrumentation for a subset of programs (services) on your system,\nthe configuration file provides a couple of settings which can be used alone or in combination to produce\nthe desired outcome:\n  - `include_paths` - A comma-separated list of glob patterns to match executable paths.\n    If you do not specify anything here, the injector defaults to instrumenting **all executables**.\n  - `exclude_paths` - A comma-separated list of glob patterns to exclude executable paths.\n  - `include_with_arguments` - A comma-separated list of glob patterns to match process arguments.\n    If you do not specify anything here, the injector defaults to instrumenting **all executables**.\n  - `exclude_with_arguments` - A comma-separated list of glob patterns to exclude process arguments.\n\nIf an executable matches both an inclusion and an exclusion criterion, the exclusion takes\nprecedence. For example, in the following configuration, all program executables in the\n`/app/system/` directory will not be instrumented, even though the `/app` directory is\nincluded for instrumentation:\n```\ndotnet_auto_instrumentation_agent_path_prefix=/usr/lib/opentelemetry/dotnet\njvm_auto_instrumentation_agent_path=/usr/lib/opentelemetry/javaagent.jar\nnodejs_auto_instrumentation_agent_path=/usr/lib/opentelemetry/otel-js/node_modules/@opentelemetry-js/otel/instrument\n\ninclude_paths=/app/*,/utilities/*\nexclude_paths=/app/system/*\n```\nTo give you an idea of what types of inclusion and exclusion criteria can be defined, let's\nlook at the following example:\n```\ndotnet_auto_instrumentation_agent_path_prefix=/usr/lib/opentelemetry/dotnet\njvm_auto_instrumentation_agent_path=/usr/lib/opentelemetry/javaagent.jar\nnodejs_auto_instrumentation_agent_path=/usr/lib/opentelemetry/otel-js/node_modules/@opentelemetry-js/otel/instrument\n\ninclude_paths=/app/*,/utilities/*,*.exe\nexclude_with_arguments=-javaagent:*,*@opentelemetry-js*,-Xmx?m\ninclude_with_arguments=*MyProject*.jar,*app.js\n```\nIn the example above we'll instrument:\n  - any programs that run from the `/app` and `/utilities` directories\n  - any programs that have an `.exe` extension\n  - any programs that have a command line argument containing `MyProject`\n  in the name and ending with the extension `.jar`\n  - any programs that have a program argument ending in `app.js`\n  - however, for all included programs, the injector **will avoid**:\n    - all programs that have a command line argument starting with\n    `-javaagent:`\n    - all programs that have a command line argument that contains `@opentelemetry-js`\n    - all `java` programs that run with a single digit megabytes of maximum memory\n\nThe example above illustrates how we avoid telemetry from unwanted applications or\ninjecting auto-instrumentation to programs that are already instrumented. If you have a\nstandard way of deploying all of your applications, you can create a default `otelinject.conf`\nfile that will ensure you get only the telemetry you want.\n\nThe `include_paths`, `exclude_paths`, `include_with_arguments` and `exclude_with_arguments` settings in\nthe configuration file are additive. This means that if you define multiple lines of these settings, the resulting\npatterns list will be a union of all of the settings. This allows for easier manipulation of the configuration\nfile with automated tools. Essentially, you can list each include or exclude rule on a separate line.\nFor example, the following two configuration files have an identical outcome:\n```\ninclude_paths=/app/*,/utilities/*,*.exe\n```\nis the same as:\n```\ninclude_paths=/app/*\ninclude_paths=/utilities/*\ninclude_paths=*.exe\n```\n\n### Design\n\nThis is a short summary of how the injector works internally:\n1. Find out which libc the process binds, if any. This is usually either glibc or musl.\n   (Some OpenTelemetry SDKs need to be injected differently, e.g. using different binaries depending on the libc\n   flavor.)\n2. If the process does not bind a libc, or it cannot be identified, the injector aborts injection and hands back control\n   to the host process.\n3. Find the location of the `dlsym` function in the loaded libc (in memory), reading ELF metadata.\n4. Use the libc's `dlsym` handle to look up more symbols in memory, in particular `__environ` and `setenv`.\n5. Again, if looking up any of the symbols fails, the injector aborts injection and hands back control to the host\n   process.\n6. Use the pointer to the `__environ` symbol to read the current environment of the process (before adding or modifying\n   any environment variables).\n7. Use the pointer to the `setenv` symbol to add or modify environment variables to add and activate OpenTelemetry\n   SDKs/auto-instrumentation agents for supported runtimes (e.g. `NODE_OPTIONS`, `JAVA_TOOL_OPTIONS`,\n   `CORECLR_PROFILER`).\n8. Use the pointer to the `setenv` symbol to add or modify `OTEL_RESOURCE_ATTRIBUTES`.\n\nThere is a much more detailed explanation of this approach, and on alternative approaches and the intricate design\nconstraints in [DESIGN.md](DESIGN.md).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n### Maintainers\n\n- [Antoine Toulme](https://github.com/atoulme), [Splunk](https://www.splunk.com/)\n- [Jacob Aronoff](https://github.com/jaronoff97), [Tero](https://www.usetero.com/)\n- [Michele Mancioppi](https://github.com/mmanciop), [Dash0](https://www.dash0.com/)\n- [Bastian Krol](https://github.com/basti1302), [Dash0](https://www.dash0.com/)\n\nFor more information about the maintainer role, see the [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#maintainer).\n\n### Project History\n\nThe code project was initially donated by [Splunk](https://www.splunk.com/) and later replaced with another code donation\nby [Dash0](https://www.dash0.com/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-telemetry%2Fopentelemetry-injector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-telemetry%2Fopentelemetry-injector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-telemetry%2Fopentelemetry-injector/lists"}