diff --git a/content/en/universal_service_monitoring/setup.md b/content/en/universal_service_monitoring/setup.md index 55901539af3..f5b205d2b77 100644 --- a/content/en/universal_service_monitoring/setup.md +++ b/content/en/universal_service_monitoring/setup.md @@ -44,6 +44,52 @@ Additional protocols and traffic encryption methods are in +Universal Service Monitoring detects service names from environment variables that exist when a process starts. USM reads these values from the operating system: from /proc/PID/environ on Linux, or through system APIs on Windows. + + +USM recognizes the following environment variables: +- `DD_SERVICE`: Explicitly sets the service name +- `DD_ENV`: Sets the environment tag +- `DD_VERSION`: Sets the version tag +- `DD_TAGS`: Additional tags; can include the `service:name` tag + +### Key limitation: USM and programmatically-set environment variables for APM + +If you set 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), these environment variables are **not** detected by USM, even though these values work for APM tracing instrumentation. + +This happens because USM runs in the Datadog Agent as a separate process and only sees the environment variables that were set when your process started. Conversely, APM instrumentation libraries run inside your application process and can read runtime environment changes. + +**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: @@ -751,6 +797,18 @@ service_monitoring_config: process_service_inference: enabled: true ``` + +
+Important limitation for non-IIS Windows services: Universal Service Monitoring on Windows uses Event Tracing for Windows (ETW) through the Microsoft-Windows-HttpService provider for HTTPS traffic monitoring. This ETW provider is only available for IIS-based services. Non-IIS services (such as custom .NET applications, Node.js servers, Java servers, or other HTTP servers running on Windows) do not support HTTPS monitoring through USM. Only plain HTTP traffic can be monitored for non-IIS Windows services. +
+ +### IIS and non-IIS service support + +| Service type | HTTP traffic monitoring | HTTPS traffic monitoring | +| --- | ----------- | ----------- | +| IIS services | Supported | Supported | +| Non-IIS services | Supported | **Not supported** | + [1]: /agent/basic_agent_usage/windows/?tab=commandline {{% /tab %}}