diff --git a/content/en/containers/docker/_index.md b/content/en/containers/docker/_index.md index 4e9837da1442b..6654261eb93c1 100644 --- a/content/en/containers/docker/_index.md +++ b/content/en/containers/docker/_index.md @@ -22,7 +22,7 @@ further_reading: text: "Collect your Prometheus metrics" - link: "/agent/docker/integrations/" tag: "Documentation" - text: "Collect automatically your applications metrics and logs" + text: "Automatically collect your application's metrics and logs" - link: "/agent/guide/autodiscovery-management/" tag: "Documentation" text: "Limit data collection to a subset of containers only" @@ -33,49 +33,70 @@ further_reading: ## Overview -The Datadog Docker Agent is the containerized version of the host [Agent][1]. The Docker Agent supports Docker, containerd, and Podman runtimes. +The Datadog Docker Agent is a version of the [Datadog Agent][1] that supports Docker, containerd, and Podman runtimes. For supported Docker versions, see [Supported Platforms][35]. -## Installation -Before installing, see the list of supported versions in the [Supported Platforms][35] documentation. To install the Datadog Agent on Docker, follow the [in-app installation instructions in Fleet Automation][34]. +## Install the Datadog Docker Agent +Follow the [in-app installation flow in Datadog][34]. {{< img src="/agent/basic_agent_usage/agent_install_docker.png" alt="In-app installation steps for the Datadog Agent on Docker." style="width:90%;">}} -## Additional configurations +## Integrations -### Integrations +After the Datadog Docker Agent is up and running, you can [configure Datadog integrations][12] to collect metrics and logs automatically from your application containers. Datadog's [Container Autodiscovery][36] enables you to define monitoring configuration for dynamic resources in containerized systems. -Once the Agent is up and running, use [Datadog's Autodiscovery feature][12] to collect metrics and logs automatically from your application containers. +## Configuration options for the Datadog Docker Agent +In a non-containerized environment, configuration options for the Datadog Agent are set in [`datadog.yaml`][13]. For the Datadog Docker Agent, you can set `datadog.yaml` configuration options through environment variables. ### Environment variables -The Agent's [main configuration file][13] is `datadog.yaml`. For the Docker Agent, `datadog.yaml` configuration options are passed in with environment variables. - #### Global options -| Env Variable | Description | -|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `DD_API_KEY` | Your Datadog API key (**required**). | -| `DD_ENV` | Sets the global `env` tag for all data emitted. | -| `DD_HOSTNAME` | Hostname to use for metrics (if autodetection fails). | -| `DD_HOSTNAME_FILE` | In some environments, auto-detection of the hostname is not adequate, and you cannot set the value with environment variables. In these cases, you can use a file on the host to provide an appropriate value. If `DD_HOSTNAME` is set to a non-empty value, this option is ignored. | -| `DD_TAGS` | Host tags separated by spaces. For example: `key1:value1 key2:value2`. | -| `DD_SITE` | Destination site for your metrics, traces, and logs. Set your Datadog site to: `{{< region-param key="dd_site" >}}`. Defaults to `datadoghq.com`. | -| `DD_DD_URL` | Optional setting to override the URL for metric submission. | -| `DD_URL` (6.36+/7.36+) | Alias for `DD_DD_URL`. Ignored if `DD_DD_URL` is already set. | -| `DD_CHECK_RUNNERS` | The Agent runs all checks concurrently by default (default value = `4` runners). To run the checks sequentially, set the value to `1`. If you need to run a high number of checks (or slow checks), the `collector-queue` component may fall behind and fail the health check. You can increase the number of runners to run checks in parallel. | -| `DD_APM_ENABLED` | Enables trace collection. Defaults to `true`. For more information about additional trace collection environment variables, see [Tracing Docker Applications][14]. | -| `DD_LOGS_CONFIG_EXPECTED_TAGS_DURATION` | In some environments, the initial logs from hosts might not include the correct tags. If you're missing tags on new hosts in your logs, include this environment variable and set it to `"10m"`.| +`DD_API_KEY` +: Your Datadog API key (**required**). + +`DD_ENV` +: Sets the global `env` tag for all data emitted. + +`DD_HOSTNAME` +: Hostname to use for metrics (if autodetection fails). + +`DD_HOSTNAME_FILE` +: In some environments, auto-detection of the hostname is not adequate, and you cannot set the value with environment variables. In these cases, you can use a file on the host to provide an appropriate value. If `DD_HOSTNAME` is set to a non-empty value, this option is ignored. + +`DD_TAGS` +: Host tags separated by spaces. For example: `key1:value1 key2:value2`. + +`DD_SITE` +: Destination site for your metrics, traces, and logs. Set your Datadog site to: `{{< region-param key="dd_site" >}}`. Defaults to `datadoghq.com`. + +`DD_DD_URL` +: Optional setting to override the URL for metric submission. + +`DD_URL` (6.36+/7.36+) +: Alias for `DD_DD_URL`. Ignored if `DD_DD_URL` is already set. + +`DD_CHECK_RUNNERS` +: The Agent runs all checks concurrently by default (default value = `4` runners). To run the checks sequentially, set the value to `1`. If you need to run a high number of checks (or slow checks), the `collector-queue` component may fall behind and fail the health check. You can increase the number of runners to run checks in parallel. + +`DD_APM_ENABLED` +: Enables trace collection. Defaults to `true`. For more information about additional trace collection environment variables, see [Tracing Docker Applications][14]. + +`DD_LOGS_CONFIG_EXPECTED_TAGS_DURATION` +: In some environments, the initial logs from hosts might not include the correct tags. If you're missing tags on new hosts in your logs, include this environment variable and set it to `"10m"`. #### Proxy settings Starting with Agent v6.4.0 (and v6.5.0 for the Trace Agent), you can override the Agent proxy settings with the following environment variables: -| Env Variable | Description | -|---------------------|-------------------------------------------------------------------| -| `DD_PROXY_HTTP` | An HTTP URL to use as a proxy for `http` requests. | -| `DD_PROXY_HTTPS` | An HTTPS URL to use as a proxy for `https` requests. | -| `DD_PROXY_NO_PROXY` | A space-separated list of URLs for which no proxy should be used. | +`DD_PROXY_HTTP` +: An HTTP URL to use as a proxy for `http` requests. + +`DD_PROXY_HTTPS` +: An HTTPS URL to use as a proxy for `https` requests. + +`DD_PROXY_NO_PROXY` +: A space-separated list of URLs for which no proxy should be used. For more information about proxy settings, see the [Agent v6 Proxy documentation][15]. @@ -83,25 +104,39 @@ For more information about proxy settings, see the [Agent v6 Proxy documentation Optional collection Agents are disabled by default for security or performance reasons. Use these environment variables to enable them: -| Env Variable | Description | -|------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `DD_APM_NON_LOCAL_TRAFFIC` | Allow non-local traffic when [tracing from other containers][16]. | -| `DD_LOGS_ENABLED` | Enable [log collection][17] with the Logs Agent. | -| `DD_PROCESS_CONFIG_PROCESS_COLLECTION_ENABLED` | Enable [live process collection][18] with the Process Agent. The [live container view][19] is already enabled by default if the Docker socket is available. | +`DD_APM_NON_LOCAL_TRAFFIC` +: Allow non-local traffic when [tracing from other containers][16]. + +`DD_LOGS_ENABLED` +: Enable [log collection][17] with the Logs Agent. + +`DD_PROCESS_CONFIG_PROCESS_COLLECTION_ENABLED` +: Enable [live process collection][18] with the Process Agent. The [live container view][19] is already enabled by default if the Docker socket is available. #### DogStatsD (custom metrics) Send custom metrics with [the StatsD protocol][20]: -| Env Variable | Description | -|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `DD_DOGSTATSD_NON_LOCAL_TRAFFIC` | Listen to DogStatsD packets from other containers (required to send custom metrics). | -| `DD_HISTOGRAM_PERCENTILES` | The histogram percentiles to compute (separated by spaces). The default is `0.95`. | -| `DD_HISTOGRAM_AGGREGATES` | The histogram aggregates to compute (separated by spaces). The default is "max median avg count". | -| `DD_DOGSTATSD_SOCKET` | Path to the unix socket to listen to. Must be in a `rw` mounted volume. | -| `DD_DOGSTATSD_ORIGIN_DETECTION` | Enable container detection and tagging for unix socket metrics. | -| `DD_DOGSTATSD_TAGS` | Additional tags to append to all metrics, events, and service checks received by this DogStatsD server, for example: `"env:golden group:retrievers"`. | -| `DD_USE_DOGSTATSD` | Enable or disable sending custom metrics from the DogStatsD library. | +`DD_DOGSTATSD_NON_LOCAL_TRAFFIC` +: Listen to DogStatsD packets from other containers (required to send custom metrics). + +`DD_HISTOGRAM_PERCENTILES` +: The histogram percentiles to compute (separated by spaces). The default is `0.95`. + +`DD_HISTOGRAM_AGGREGATES` +: The histogram aggregates to compute (separated by spaces). The default is `"max median avg count"`. + +`DD_DOGSTATSD_SOCKET` +: Path to the unix socket to listen to. Must be in a `rw` mounted volume. + +`DD_DOGSTATSD_ORIGIN_DETECTION` +: Enable container detection and tagging for UNIX socket metrics. + +`DD_DOGSTATSD_TAGS` +: Additional tags to append to all metrics, events, and service checks received by this DogStatsD server. For example: `"env:golden group:retrievers"`. + +`DD_USE_DOGSTATSD` +: Enable or disable sending custom metrics from the DogStatsD library. Learn more about [DogStatsD over Unix Domain Sockets][21]. #### Tagging @@ -110,11 +145,14 @@ As a best practice, Datadog recommends using [unified service tagging][22] when Datadog automatically collects common tags from Docker, Kubernetes, ECS, Swarm, Mesos, Nomad, and Rancher. To extract even more tags, use the following options: -| Env Variable | Description | -|-------------------------------|---------------------------------------------------------------------------------------------------------| -| `DD_CONTAINER_LABELS_AS_TAGS` | Extract container labels. This env is equivalent to the old `DD_DOCKER_LABELS_AS_TAGS` env. | -| `DD_CONTAINER_ENV_AS_TAGS` | Extract container environment variables. This env is equivalent to the old `DD_DOCKER_ENV_AS_TAGS` env. | -| `DD_COLLECT_EC2_TAGS` | Extract custom EC2 tags without using the AWS integration. | +`DD_CONTAINER_LABELS_AS_TAGS` +: Extract container labels. This env is equivalent to `DD_DOCKER_LABELS_AS_TAGS`. + +`DD_CONTAINER_ENV_AS_TAGS` +: Extract container environment variables. This env is equivalent to `DD_DOCKER_ENV_AS_TAGS`. + +`DD_COLLECT_EC2_TAGS` +: Extract custom EC2 tags without using the AWS integration. See the [Docker Tag Extraction][23] documentation to learn more. @@ -126,16 +164,29 @@ Integration credentials can be stored in Docker or Kubernetes secrets and used i Exclude containers from logs collection, metrics collection, and Autodiscovery. Datadog excludes Kubernetes and OpenShift `pause` containers by default. These allowlists and blocklists apply to Autodiscovery only; traces and DogStatsD are not affected. The value for these environment variables support regular expressions. -| Env Variable | Description | -|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `DD_CONTAINER_INCLUDE` | Allowlist of containers to include (separated by spaces). Use `.*` to include all. For example: `"image:image_name_1 image:image_name_2"`, `image:.*` When using ImageStreams inside OpenShift environments, use the container name instead of image. For example:"name:container_name_1 name:container_name_2", name:.* | -| `DD_CONTAINER_EXCLUDE` | Blocklist of containers to exclude (separated by spaces). Use `.*` to exclude all. For example: `"image:image_name_3 image:image_name_4"` (**Note**: This variable is only honored for Autodiscovery.), `image:.*` | -| `DD_CONTAINER_INCLUDE_METRICS` | Allowlist of containers whose metrics you wish to include. | -| `DD_CONTAINER_EXCLUDE_METRICS` | Blocklist of containers whose metrics you wish to exclude. | -| `DD_CONTAINER_INCLUDE_LOGS` | Allowlist of containers whose logs you wish to include. | -| `DD_CONTAINER_EXCLUDE_LOGS` | Blocklist of containers whose logs you wish to exclude. | -| `DD_AC_INCLUDE` | **Deprecated**. Allowlist of containers to include (separated by spaces). Use `.*` to include all. For example: `"image:image_name_1 image:image_name_2"`, `image:.*` | -| `DD_AC_EXCLUDE` | **Deprecated**. Blocklist of containers to exclude (separated by spaces). Use `.*` to exclude all. For example: `"image:image_name_3 image:image_name_4"` (**Note**: This variable is only honored for Autodiscovery.), `image:.*` | +`DD_CONTAINER_INCLUDE` +: Allowlist of containers to include (separated by spaces). Use `.*` to include all. For example: `"image:image_name_1 image:image_name_2"`, `image:.*` When using ImageStreams inside OpenShift environments, use the container name instead of image. For example: `"name:container_name_1 name:container_name_2"`, `name:.*` + +`DD_CONTAINER_EXCLUDE` +: Blocklist of containers to exclude (separated by spaces). Use `.*` to exclude all. For example: `"image:image_name_3 image:image_name_4"`, `image:.*` (**Note**: This variable is only honored for Autodiscovery.) + +`DD_CONTAINER_INCLUDE_METRICS` +: Allowlist of containers whose metrics you wish to include. + +`DD_CONTAINER_EXCLUDE_METRICS` +: Blocklist of containers whose metrics you wish to exclude. + +`DD_CONTAINER_INCLUDE_LOGS` +: Allowlist of containers whose logs you wish to include. + +`DD_CONTAINER_EXCLUDE_LOGS` +: Blocklist of containers whose logs you wish to exclude. + +`DD_AC_INCLUDE` +: **Deprecated**. Allowlist of containers to include (separated by spaces). Use `.*` to include all. For example: `"image:image_name_1 image:image_name_2"`, `image:.*` + +`DD_AC_EXCLUDE` +: **Deprecated**. Blocklist of containers to exclude (separated by spaces). Use `.*` to exclude all. For example: `"image:image_name_3 image:image_name_4"`, `image:.*` (**Note**: This variable is only honored for Autodiscovery.) Additional examples are available on the [Container Discover Management][25] page. @@ -145,19 +196,25 @@ Additional examples are available on the [Container Discover Management][25] pag #### Autodiscovery -| Env Variable | Description | -|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `DD_LISTENERS` | Autodiscovery listeners to run. | -| `DD_EXTRA_LISTENERS` | Additional Autodiscovery listeners to run. They are added in addition to the variables defined in the `listeners` section of the `datadog.yaml` configuration file. | -| `DD_CONFIG_PROVIDERS` | The providers the Agent should call to collect checks configurations. The default provider is `docker`. The Docker provider handles templates embedded in container labels. | -| `DD_EXTRA_CONFIG_PROVIDERS` | Additional Autodiscovery configuration providers to use. They are added in addition to the variables defined in the `config_providers` section of the `datadog.yaml` configuration file. | +`DD_LISTENERS` +: Autodiscovery listeners to run. + +`DD_EXTRA_LISTENERS` +: Additional Autodiscovery listeners to run. They are added in addition to the variables defined in the `listeners` section of the `datadog.yaml` configuration file. + +`DD_CONFIG_PROVIDERS` +: The providers the Agent should call to collect checks configurations. The default provider is `docker`. The Docker provider handles templates embedded in container labels. + +`DD_EXTRA_CONFIG_PROVIDERS` +: Additional Autodiscovery configuration providers to use. They are added in addition to the variables defined in the `config_providers` section of the `datadog.yaml` configuration file. #### Miscellaneous -| Env Variable | Description | -|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `DD_PROCESS_AGENT_CONTAINER_SOURCE` | Overrides container source auto-detection to force a single source. e.g `"docker"`, `"ecs_fargate"`, `"kubelet"`. This is no longer needed since Agent v7.35.0. | -| `DD_HEALTH_PORT` | Set this to `5555` to expose the Agent health check at port `5555`. | +`DD_PROCESS_AGENT_CONTAINER_SOURCE` +: Overrides container source auto-detection to force a single source. e.g `"docker"`, `"ecs_fargate"`, `"kubelet"`. This is no longer needed since Agent v7.35.0. + +`DD_HEALTH_PORT` +: Set this to `5555` to expose the Agent health check at port `5555`. ## Commands @@ -227,4 +284,5 @@ If you installed the Datadog Docker Agent with Single Step APM Instrumentation, [32]: /integrations/ntp/#metrics [33]: /tracing/trace_collection/automatic_instrumentation/single-step-apm/?tab=docker#removing-apm-for-all-services-on-the-infrastructure [34]: https://app.datadoghq.com/account/settings/agent/latest?platform=docker -[35]: https://docs.datadoghq.com/agent/supported_platforms/?tab=cloudandcontainers +[35]: /agent/supported_platforms/?tab=cloudandcontainers +[36]: /getting_started/containers/autodiscovery \ No newline at end of file