Understand the Agent Configuration

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

The agent relies on a pair of configuration files to define metrics collection parameters:

dragent.default.yaml

The core configuration file. You can look at it to understand more about the default configurations provided.

Location: "/opt/draios/etc/dragent.default.yaml."

CAUTION. This file should never be edited.

dragent.yaml or configmap.yaml (Kubernetes)

The configuration file where parameters can be added, either directly in YAML as name/value pairs, or using environment variables such as 'ADDITIONAL_CONF." Location: "/opt/draios/etc/dragent.yaml."

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.

Note

One additional file, dragent.auto.yaml is also created and used in special circumstances. See Optional: Agent Auto-Config for more detail.

Access and Edit the Config File

There are various ways to add or edit parameters indragent.yaml.

Option 1: With dragent.yaml (for testing)

It is possible to edit the container’s file directly on the host.

Add parameters directly in YAML.

  1. Access dragent.yamldirectly at"/opt/draios/etc/dragent.yaml."

  2. Edit the file. Use proper YAML syntax.

    See the examples at the bottom of the page.

  3. Restart the agent for changes to take effect

  • Native agent: service dragent restart

  • Container agent: docker restart sysdig-agent

Option 2: With configmap.yaml(Kubernetes)

Configmap.yaml is the configuration file where parameters can be added, either directly in YAML as name/value pairs, or using environment variables such as 'ADDTIONAL_CONF."

If you install agents as DaemonSets on a system running Kubernetes, you use configmap.yaml to connect with and manipulate the underlyingdragent.yamlfile.

See also: Agent Install: Kubernetes | GKE | OpenShift | IBM

Add parameters directly in YAML.

Edit the files locally and apply with the changes withkubectl -f.

  1. Access theconfigmap.yaml.

  2. Edit the file as needed.

  3. Apply the changes:

    kubectl apply -f sysdig-agent-configmap.yaml

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

Option 3: With Docker Run (Docker)

Add-e ADDITIONAL_CONF=”<VARIABLES>”to a Docker run command, where <VARIABLES> contains all the customized parameters you want to include, in a single-line format.

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 format.

You can do the conversion manually for short snippets. To convert longer portions of YAML, use echo|sed commands.

Note

In earlier versions, the Sysdig Agent connected to port 6666. This behavior has been deprecated, as the Sysdig agent now connects to port 6443.

The basic procedure:

  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.

    sed script: " | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g'

  3. Insert the resulting line into a Docker run command or add it to the daemonset file as an ADDITIONAL_CONF.

Example: simple

Insert parameters to turn off StatsD collection and blacklist port 6443.

YAML format

statsd enabled: false blackisted_ports: - 6443

Single-line format (manual)

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

ADDITIONAL_CONF="statsd:\n disabled: false\nblacklisted_ports:\n - 6443"

Here the single line is incorporated into a full agent startup Docker command.

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\nblacklisted_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 sysdig/agent
Example: complex

Insert parameters to override the default configuration for a RabbitMQ app check.

YAML format 

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

Single-line format (echo |sed)

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

echo "app_checks:
  - name: rabbitmq
    pattern:
      port: 15672
    conf:
      rabbitmq_api_url: "http://localhost:15672/api/"
      rabbitmq_user: myuser
      rabbitmq_pass: mypassword
      queues:
        - 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"

Option 4: With HELM Format

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

Example

$helm install --name sysdig-agent-1 --set 
sysdig.settings.tags='linux:ubuntu,dept:dev,local:nyc' --set 
sysdig.settings.k8s_cluster_name='my_cluster' stable/sysdig

Will be transformed into

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

Table 1: Environment Variables for Agent Config File

Name

Value

Description

ACCESS_KEY

<your Sysdig access key>

Required

TAGS

<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.

COLLECTOR

<collector-hostname.com> or 111.222.333.400

Enter the host name or IP address of the Sysdig collector service. Note that when used within dragent.yaml, must be lowercase collector.

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

COLLECTOR_PORT

6443

On-prem only. The port used by the Sysdig collector service; default 6443.

SECURE

"true"

On-prem only. If using SSL/TLS to connect to collector service value = "true" otherwise "false."

CHECK_CERTIFICATE

"false"

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

ADDITIONAL_CONF

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

SYSDIG_PROBE_URL

Optional. An alternative URL to download precompiled kernel module.

Sample Docker Command Using 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 CHECK_CERTIFICATE=false -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 sysdig/agent

Table 1: Environment Variables for Agent Config File

Name

Value

Description

ACCESS_KEY

<your Sysdig access key>

Required

TAGS

<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.

COLLECTOR

<collector-hostname.com> or 111.222.333.400

Enter the host name or IP address of the Sysdig collector service. Note that when used within dragent.yaml, must be lowercase collector.

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

COLLECTOR_PORT

6443

On-prem only. The port used by the Sysdig collector service; default 6443.

SECURE

"true"

On-prem only. If using SSL/TLS to connect to collector service value = "true" otherwise "false."

CHECK_CERTIFICATE

"false"

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

ADDITIONAL_CONF

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

SYSDIG_PROBE_URL

Optional. An alternative URL to download precompiled kernel module.

Sample Docker Command Using 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 CHECK_CERTIFICATE=false -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 sysdig/agent