From 1f069f383ab40f8d220f60382281e8296afc2667 Mon Sep 17 00:00:00 2001
From: Ofir Yefet <ofir.yefet@datadoghq.com>
Date: Wed, 5 Nov 2025 20:43:16 +0200
Subject: [PATCH] Clarify USM environment variable detection limitations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation explaining that Universal Service Monitoring (USM) only
detects environment variables set at process start time, not those set
programmatically within application code.

This clarifies that while APM instrumentation libraries can read DD_SERVICE
and similar variables set via System.setProperty() (Java) or
Environment.SetEnvironmentVariable() (.NET), USM cannot detect these as it
reads from /proc/PID/environ (Linux) or system APIs (Windows) which only
contain the initial process environment.

Includes examples for properly setting environment variables in Docker,
Kubernetes, and shell environments to ensure USM detection.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../en/universal_service_monitoring/setup.md  | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/content/en/universal_service_monitoring/setup.md b/content/en/universal_service_monitoring/setup.md
index 55901539af3..b650ed29fa2 100644
--- a/content/en/universal_service_monitoring/setup.md
+++ b/content/en/universal_service_monitoring/setup.md
@@ -44,6 +44,55 @@ Additional protocols and traffic encryption methods are in <a href="/universal_s
 - Datadog Agent is installed alongside your service. Installing a tracing library is _not_ required.
 - The `env` tag for [Unified Service Tagging][1] has been applied to your deployment. The `service` and `version` tags are optional.
 
+## How USM detects service names
+
+<div class="alert alert-warning">
+<strong>Important:</strong> Universal Service Monitoring detects service names from environment variables that exist when a process starts. USM reads these values from the operating system (from <code>/proc/PID/environ</code> on Linux or via system APIs on Windows).
+</div>
+
+**Environment variables USM recognizes:**
+- `DD_SERVICE` - Explicitly sets the service name
+- `DD_TAGS` - Can include `service:name` tag
+- `DD_ENV` - Sets the environment tag
+- `DD_VERSION` - Sets the version tag
+
+**Key limitation:**
+
+Setting environment variables programmatically **inside your application code** (such as `System.setProperty("dd.service", "my-service")` in Java or `Environment.SetEnvironmentVariable("DD_SERVICE", "my-service")` in .NET) will **not** be detected by USM, even though these values work for APM tracing instrumentation.
+
+**Why this happens:**
+
+- **APM instrumentation libraries** run inside your application process and can read runtime environment changes
+- **USM runs in the Datadog Agent** as a separate process and only sees the environment variables that were set when your process started
+
+**To ensure USM detection, set environment variables before the application starts:**
+
+{{< tabs >}}
+{{% tab "Docker" %}}
+```yaml
+environment:
+  - DD_SERVICE=my-service
+  - DD_ENV=production
+```
+{{% /tab %}}
+{{% tab "Kubernetes" %}}
+```yaml
+env:
+  - name: DD_SERVICE
+    value: "my-service"
+  - name: DD_ENV
+    value: "production"
+```
+{{% /tab %}}
+{{% tab "Shell" %}}
+```bash
+export DD_SERVICE=my-service
+export DD_ENV=production
+java -jar myapp.jar
+```
+{{% /tab %}}
+{{< /tabs >}}
+
 ## Enabling Universal Service Monitoring
 
 Enable Universal Service Monitoring in your Agent by using one of the following methods depending on how your service is deployed and your Agent configured: