-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
README: add more comprehensive instructions for running the agent
this adds more comprehensive instructions to run the agent, and separate instructions for Kubernetes / Docker and running directly on the host (while recommending the first two).
- Loading branch information
Showing
4 changed files
with
198 additions
and
85 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # Running the agent in Docker | ||
|
|
||
| This document is a guide to running the application in a Docker container. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| The datadog-agent must be running on the host and configured to collect APM data (this is enabled by default in the agent, unless you explicitly disabled it). See https://docs.datadoghq.com/containers/docker/apm/ for more information. | ||
|
|
||
| For the purposes of this guide, we assume that the datadog agent is accessible at a specific address from the docker container: `http://<agent_address>:8126`. | ||
|
|
||
| ## Running the profiler | ||
|
|
||
| See https://github.com/DataDog/otel-profiling-agent/pkgs/container/otel-profiling-agent/ for a container image that can be used to run the profiler. | ||
|
|
||
| To run the profiler in Docker, you should ensure the following requirements are met (see example below): | ||
| 1. The container has host PID enabled. | ||
| 2. The container is running in privileged mode. | ||
| 3. The container has the `SYS_ADMIN` capability. | ||
| 4. The `OTEL_PROFILING_AGENT_COLLECTION_AGENT` environment variable is set to the address of the Datadog agent: `http://<agent_address>:8126`. | ||
|
|
||
| Additionally, to be able to resolve container names, the profiler needs access to the container runtime socket. This is done by mounting the container runtime socket into the profiler container. | ||
|
|
||
| ### Example command to run the profiler in Docker | ||
|
|
||
| ```bash | ||
| docker run \ | ||
| --pid=host \ | ||
| --privileged \ | ||
| --cap-add=SYS_ADMIN \ | ||
| -e OTEL_PROFILING_AGENT_COLLECTION_AGENT=http://<agent_address>:8126 \ | ||
| -e OTEL_PROFILING_AGENT_TAGS="service:$(hostname)" \ | ||
| -v /var/run/docker.sock:/var/run/docker.sock \ | ||
| ghcr.io/datadog/otel-profiling-agent:latest | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,109 @@ | ||
| # Running the profiler in Kubernetes | ||
|
|
||
| This document is a guide to running the profiler in a Kubernetes cluster. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| The datadog-agent must be running in the cluster and configured to collect APM data (this is enabled by default in the agent, unless you explicitly disabled it). See https://docs.datadoghq.com/containers/kubernetes/apm/ for more information. | ||
|
|
||
| For the purposes of this guide, we assume that the datadog agent is accessible at a specific address: `http://<agent_address>:8126`. | ||
|
|
||
| ## Running the profiler | ||
|
|
||
| See https://github.com/DataDog/otel-profiling-agent/pkgs/container/otel-profiling-agent/ for a container image that can be used to run the profiler. | ||
|
|
||
| To run the profiler in a Kubernetes cluster, you should ensure the following requirements are met (see example below): | ||
| 1. The container has host PID enabled. | ||
| 2. The container is running in privileged mode. | ||
| 3. The `procMount` security context field is set to `Unmasked`. | ||
| 4. The container has the `SYS_ADMIN` capability. | ||
| 5. The `OTEL_PROFILING_AGENT_COLLECTION_AGENT` environment variable is set to the address of the Datadog agent: `http://<agent_address>:8126`. | ||
|
|
||
| Additionally, to be able to resolve pod names in Kubernetes, the profiler needs: | ||
| * The `KUBERNETES_NODE_NAME` environment variable set to the name of the node where the profiler is running. | ||
| * A ClusterRole and ClusterRoleBinding configured (see below). | ||
|
|
||
| ### Example spec | ||
|
|
||
| The profiler pod spec excerpt: | ||
| ```yaml | ||
| apiVersion: apps/v1 | ||
| # ... | ||
| spec: | ||
| # ... | ||
| template: | ||
| # ... | ||
| spec: | ||
| # ... | ||
| serviceAccountName: <my-service-account> # The service account used | ||
| hostPID: true # Setting hostPID to true (1.) | ||
| containers: | ||
| - name: otel-profiling-agent | ||
| securityContext: | ||
| runAsUser: 0 | ||
| privileged: true # Running in privileged mode (2.) | ||
| procMount: Unmasked # Setting procMount to Unmasked (3.) | ||
| capabilities: | ||
| add: | ||
| - SYS_ADMIN # Adding SYS_ADMIN capability (4.) | ||
| env: | ||
| - name: OTEL_PROFILING_AGENT_COLLECTION_AGENT # The address of the Datadog agent (5.) | ||
| value: "http://<agent_address>:8126" | ||
| - name: KUBERNETES_NODE_NAME # this is needed to resolve pod names in Kubernetes | ||
| valueFrom: | ||
| fieldRef: | ||
| fieldPath: spec.nodeName | ||
| - name: OTEL_PROFILING_AGENT_TAGS | ||
| value: "service:$(KUBERNETES_NODE_NAME)" # will inherit the variable set above | ||
| # ... | ||
| volumeMounts: | ||
| - name: containerd # Or alternatively, docker if using docker. This is required to be able to resolve container names. | ||
| mountPath: /run/containerd/containerd.sock # Or alternatively, /var/run/docker.sock | ||
| # ... | ||
| volumes: | ||
| - name: containerd # Or alternatively, docker if using docker | ||
| hostPath: | ||
| path: /run/containerd/containerd.sock # Or alternatively, /var/run/docker.sock | ||
| type: Socket | ||
| # ... | ||
| ``` | ||
|
|
||
| You will also need to create a ServiceAccount, ClusterRole, and ClusterRoleBinding for the profiler to be able to list pods in the cluster. Here is an example: | ||
| ```yaml | ||
| apiVersion: v1 | ||
| kind: ServiceAccount | ||
| metadata: | ||
| name: <my-service-account> | ||
| namespace: <my-service-account-namespace> | ||
| # ... | ||
| --- | ||
| apiVersion: rbac.authorization.k8s.io/v1 | ||
| kind: ClusterRole | ||
| metadata: | ||
| name: <my-cluster-role> | ||
| # ... | ||
| rules: | ||
| - apiGroups: | ||
| - "" | ||
| resources: | ||
| - nodes | ||
| - pods | ||
| verbs: | ||
| - get | ||
| - list | ||
| - watch | ||
| --- | ||
| apiVersion: rbac.authorization.k8s.io/v1 | ||
| kind: ClusterRoleBinding | ||
| metadata: | ||
| name: <my-cluster-role-binding> | ||
| # ... | ||
| subjects: | ||
| - kind: ServiceAccount | ||
| name: <my-service-account> | ||
| namespace: <my-service-account-namespace> | ||
| roleRef: | ||
| kind: ClusterRole | ||
| name: <my-cluster-role> | ||
| apiGroup: rbac.authorization.k8s.io | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # Running the agent directly on the host | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| The datadog-agent must be running on the host and configured to collect APM data (this is enabled by default in the agent, unless you explicitly disabled it). See agent installation instructions [here](https://docs.datadoghq.com/agent/) and the flag to enable APM [here](https://github.com/DataDog/datadog-agent/blob/8a80bcd1c1460ba9caa97d974568bd9d0c702f3f/pkg/config/config_template.yaml#L1036-L1042). | ||
|
|
||
| For the purposes of this guide, we assume that the datadog agent is accessible at a specific address from the docker container: `http://localhost:8126`. | ||
|
|
||
| ## Installation | ||
|
|
||
| Download pre-built amd64 and arm64 binaries for our [latest release](https://github.com/DataDog/otel-profiling-agent/releases/latest). | ||
|
|
||
| Alternatively, you can build the profiler from source. The following instructions assume you have docker installed. | ||
|
|
||
| <details> | ||
| <summary>Manual build instructions</summary> | ||
| <br /> | ||
|
|
||
| To build the profiler, you can use the following commands: | ||
|
|
||
| ``` | ||
| make docker-image | ||
| make agent | ||
| ``` | ||
|
|
||
| This will create a `otel-profiling-agent` binary in the current directory. | ||
|
|
||
| </details> | ||
|
|
||
| ## Running the profiler | ||
|
|
||
| To run the profiler, you need to make sure that debugfs is mounted. If it's not, you can run: | ||
|
|
||
| ``` | ||
| sudo mount -t debugfs none /sys/kernel/debug | ||
| ``` | ||
|
|
||
| After that, you can start the profiler as shown below (make sure you run it as root): | ||
|
|
||
| ``` | ||
| sudo otel-profiling-agent -tags "service:$(hostname)" -collection-agent "http://localhost:8126" | ||
| ``` | ||
|
|
||
| If your datadog agent is reachable under a different address, you can modify the `-collection-agent` parameter accordingly. |