Understand the Agent Configuration

Out of the box, the Sysdig agent will gather and report on a wide variety of predefined metrics. It can also accommodate any number of custom parameters for additional metrics collection.

The agent relies on a configuration file named dragent.yaml to define metrics collection parameters. This file is located in the /opt/draios/etc/ directory. You can add configuration parameters directly in YAML as key-value pairs, or using the environment variable such as ADDITIONAL_CONF.

The dragent.yaml file can be accessed and edited in several ways, depending on how the agent was installed. This document describes how to modify dragent.yaml.


For more information about configuring each of the three environments listed in this section, see Edit the Configuration File.


If Sysdig agent is installed in a Kubernetes environment, you can edit the dragent.yaml file using one of the following options:

  • values.yaml

  • ConfigMap

  • sysdig-deploy Helm chart


If Sysdig agent is installed in a non-orchestrated environment such as Docker, you can edit the dragent.yaml file using one of the following options:

  • dragent.yaml
  • docker run


If Sysdig agent is installed in a Linux host, edit the dragent.yaml file directly.

Edit the Configuration File


  1. Log in to the host where the agent is installed.

  2. Open /opt/draios/etc/dragent.yaml.

  3. Edit the file using proper YAML syntax. See the examples at the bottom of the page.

  4. Restart the agent for changes to take effect.

    • Linux: service dragent restart

    • Non-orchestrated: docker restart sysdig-agent


If you install the agent using DaemonSets on a Kubernetes cluster, you use configmap.yaml to connect with and manipulate the underlying dragent.yaml file.

Use the following ways to add parameters to configmap.yaml:

  • Directly edit configmap.yaml in YAML as key-value pairs.

  • Use environment variables such as ADDITIONAL_CONF.

You can edit the files locally and apply the changes with kubectl -f:

  1. Open the configmap.yaml file.

  2. Edit the file as needed.

  3. Apply the changes:

    kubectl apply -f sysdig-agent-configmap.yaml

All the running agents will automatically pick the new configuration after Kubernetes pushes the changes across all the nodes in the cluster.

docker run

Run the docker run command with -e ADDITIONAL_CONF="<VARIABLES>" where <VARIABLES> contains all the customized parameters you want to include.

Convert YAML Parameters to Single-Line Format

To insert ADDITIONAL_CONF parameters in a docker run command or a DaemonSet file, you must convert the YAML code into a single line. You can do the conversion manually for short snippets. To convert longer portions of YAML, use echo|sed commands.

  1. Write your configuration in YAML, as it would be entered directly in dragent.yaml.

  2. In a Bash shell, use echo and sed to convert to a single line:

    echo "<YAML_CONTENT>" | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g'

  3. Insert the resulting line into the docker run command or add it to the DaemonSet file as an ADDITIONAL_CONF.


Disable StatsD Collection

This example shows how to turn off StatsD collection and blacklist port 6443.

Sysdig agent uses port 6443 for both inbound and outbound communication with the Sysdig backend. The agent initiates a request and keeps a connection open with the Sysdig backend for the backend to push configurations, Falco rules, policies, and so on.

Ensure that you allow the agents’ inbound and outbound communication on TCP 6443 from the respective IP addresses associated with your SaaS Regions. Note that you are allowing the agent to send communication outbound on TCP 6443 to the inbound IP ranges listed in the SaaS Regions.

YAML Format
    enabled: false
    - 6443
Single-Line Format

Use spaces, hyphens, and \n correctly when manually converting to a single line:

ADDITIONAL_CONF="statsd:\n enabled: false\n blacklisted_ports:\n - 6443"

You can run a full agent startup Docker command in a single line as follows:

docker run
  --name sysdig-agent \
  --privileged \
  --net host \
  --pid host \
  -e ACCESS_KEY=1234-your-key-here-1234 \
  -e TAGS=dept:sales,local:NYC \
  -e ADDITIONAL_CONF="statsd:\n    enabled: false\n    blacklisted_ports:\n    - 6443" \
  -v /var/run/docker.sock:/host/var/run/docker.sock \
  -v /dev:/host/dev \
  -v /proc:/host/proc:ro \
  -v /boot:/host/boot:ro \
  -v /lib/modules:/host/lib/modules:ro \
  -v /usr:/host/usr:ro \
Add RabbitMQ App Check

This example helps you override the default configuration for a RabbitMQ app check.

YAML Format
  - name: rabbitmq
      port: 15672
      rabbitmq_api_url: "http://localhost:15672/api/"
      rabbitmq_user: myuser
      rabbitmq_pass: mypassword
        - MyQueue1
        - MyQueue2
Single-Line Format (echo | sed)

From a Bash shell, issue the echo command and sed script.

echo "app_checks:
  - name: rabbitmq
      port: 15672
      rabbitmq_api_url: "http://localhost:15672/api/"
      rabbitmq_user: myuser
      rabbitmq_pass: mypassword
        - MyQueue1
        - MyQueue2
" | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g'

This results in the single-line format to be used with ADDITIONAL_CONF in a Docker command or DaemonSet file.

"app_checks:\n - name: rabbitmq\n  pattern:\n    port: 15672\n  conf:\n    rabbitmq_api_url: http://localhost:15672/api/\n    rabbitmq_user: myuser\n    rabbitmq_pass: mypassword\n    queues:\n      - MyQueue1\n      - MyQueue2\n"

helm install

If you installed the Sysdig agent in Kubernetes using the Helm chart, then no configmap.yaml file was downloaded. You can edit dragent.yaml using the Helm syntax:

helm install \
  --namespace sysdig-agent \
  --set agent.sysdig.settings.tags='linux:ubuntu\,dept:dev\,local:nyc' \
  --set global.clusterConfig.name='my_cluster' \

This command will be translated into the following:

  dragent.yaml: |
    tags: linux:ubuntu,dept:dev,local:nyc
    k8s_cluster_name: my_cluster    

Environment Variables for Agent Configuration File





Your Sysdig access key.



Meaningful tags you want applied to your instances.

Optional. These are displayed in Sysdig Monitor for ease of use.

For example:

tags: linux:ubuntu,dept:dev,local:nyc

See sysdig-agent-configmap.yaml.


The region associated with your Sysdig application.

Enter the SaaS region.


<collector-hostname.com> or 111.222.333.400

Enter the hostname or IP address of the Sysdig collector service. Note that when used within dragent.yaml, it must be lowercase (collector).

For SaaS regions, see: SaaS Regions and IP Ranges.



On-prem only. The port used by the Sysdig collector service. Default: 6443.



On-prem only. If using SSL/TLS to connect to collector service, set the value to true, otherwise to false.



On-prem only. Set to true when using SSL/TLS to connect to the collector service and should check for a valid SSL/TLS certificate.


Optional. A place to provide custom configuration values to the agent as environment variables.


Optional. An alternative URL to download precompiled kernel modules.

Here is a sample Docker command using environment variables:

docker run \
  --name sysdig-agent \
  --privileged \
  --net host \
  --pid host \
  -e ACCESS_KEY=3e762f9a-3936-4c60-9cf4-c67e7ce5793b \
  -e COLLECTOR=mycollector.elb.us-west-1.amazonaws.com \
  -e COLLECTOR_PORT=6443 \
  -e TAGS=my_tag:some_value \
  -e ADDITIONAL_CONF="log:\n file_priority: debug\n console_priority: error" \
  -v /var/run/docker.sock:/host/var/run/docker.sock \
  -v /dev:/host/dev \
  -v /proc:/host/proc:ro \
  -v /boot:/host/boot:ro \
  -v /lib/modules:/host/lib/modules:ro \
  -v /usr:/host/usr:ro \
  --shm-size=350m \