# Datadog Agent

> Use when installing, configuring, or updating Datadog Agent;

- **Type:** Skill
- **Install:** `agentstack add skill-cogni-ai-ou-cogni-ai-agent-skills-datadog-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Cogni-AI-OU](https://agentstack.voostack.com/s/cogni-ai-ou)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Cogni-AI-OU](https://github.com/Cogni-AI-OU)
- **Source:** https://github.com/Cogni-AI-OU/cogni-ai-agent-skills/tree/main/datadog-agent

## Install

```sh
agentstack add skill-cogni-ai-ou-cogni-ai-agent-skills-datadog-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skill: datadog-agent

Expert-level guidance for installing, configuring, and extending the Datadog Agent, including Ansible orchestration and custom OpenMetrics checks.

## When to Use

- When configuring, installing, or troubleshooting the Datadog Agent on a Linux host.
- To write custom Python check scripts (`AgentCheck` or `OpenMetricsBaseCheckV2`) for the agent.
- When updating Ansible playbooks that deploy the `datadog.dd.agent` role.

## When Not to Use

- For querying Datadog APIs to read telemetry or dashboard data (use `datadog-api` instead).
- When managing Datadog SaaS configurations like Monitors or SLOs (use `datadog-monitors`).
- If you are deploying Datadog strictly via a Helm chart in Kubernetes without needing custom host-level Python checks.

## Common Pitfalls

- **Subprocess Hangs**: Using Python's native `subprocess` module inside a custom check instead of `get_subprocess_output()`, which deadlocks the Agent's Go-runtime.
- **Misnamed Files**: Creating a custom check script named `my_check.py` but naming the configuration file `custom_check.yaml`, causing the Agent to silently ignore it.
- **Root Level Logs**: Defining `- type: file` at the root of a check's YAML configuration instead of properly nesting it under a `logs:` key.

## Core Principles

- **Agent Immutability**: Prefer immutable configuration deployments (e.g., Ansible) over manual modifications to `datadog.yaml` or `conf.d/`.
- **API Key Handling**: Never hardcode `datadog_api_key` in playbooks; utilize vault secrets or environment variables.
- **Python Compatibility**: Custom Agent checks must be Python 3 compatible for modern Agent versions (v7+).
- **File Matching**: The custom check script name (e.g., `my_check.py`) must exactly match its configuration file name (e.g., `my_check.yaml`).

## Ansible Integration & Logs Configuration

When using the `datadog.dd.agent` (or legacy `datadog.datadog`) Ansible role, ensure correct YAML hierarchy, especially for log collection.

- **Requirements**: Ansible v2.10+, `ansible-galaxy collection install datadog.dd`
- **Avoid Array Root**: Do not map a check directly to an array. A common mistake with logs is defining `- type: file` at the root check level.
- **Correct Logs Structure**: Logs must be encapsulated under a `logs:` key within the specific check dictionary.

```yaml
# Correct Ansible definition for logs attached to a custom/syslog check
datadog_checks:
  syslog: # Creates /etc/datadog-agent/conf.d/syslog.d/conf.yaml
    logs:
      - type: file
        path: /var/log/syslog
        service: syslog
        source: syslog
```

## Custom Agent Checks

Create custom Python checks by extending `AgentCheck` for simple metrics or `OpenMetricsBaseCheckV2` for Prometheus endpoints.

- **Directory Paths**:
  - Scripts: `/etc/datadog-agent/checks.d/`
  - Configs: `/etc/datadog-agent/conf.d/.d/conf.yaml`
- **Naming Convention**: Prefix custom checks with `custom_` (e.g., `custom_postfix.py`) to avoid conflicts with out-of-the-box integrations.
- **Check Verification**: `sudo -u dd-agent -- datadog-agent check `

### Simple Python Check

```python
from datadog_checks.base import AgentCheck

class CustomCheck(AgentCheck):
    def check(self, instance):
        self.gauge('custom.metric', 1, tags=instance.get('tags', []))
```

### OpenMetrics Base Check (V2)

Advanced scraping from Prometheus endpoints. Requires `openmetrics_endpoint` in the check config.

```python
from datadog_checks.base import OpenMetricsBaseCheckV2, ConfigurationError

class CustomOpenMetricsCheck(OpenMetricsBaseCheckV2):
    __NAMESPACE__ = "my_namespace"

    def __init__(self, name, init_config, instances):
        super(CustomOpenMetricsCheck, self).__init__(name, init_config, instances)
        self.metrics_map = {
            'prom_metric_name': 'datadog.metric.name',
        }

    def get_default_config(self):
        return {'metrics': self.metrics_map}

    def check(self, instance):
        endpoint = instance.get('openmetrics_endpoint')
        if not endpoint:
            raise ConfigurationError("Missing 'openmetrics_endpoint'")
        super().check(instance)
```

## Integrations & Developer Platform

- **Tiles & Dashboards**: Official integrations must include out-of-the-box dashboards and telemetry logic. API integrations require OAuth 2.0.
- **Platform Separation**: Agent-based integrations collect from local hosts, whereas API-based integrations ingest directly via Datadog REST endpoints.

## Diagnostics and Troubleshooting

- Check agent status: `datadog-agent status`
- **Subprocess execution**: Never use Python's native `subprocess` module due to the Agent's Go-runtime multithreading constraints. Always use `get_subprocess_output()` from `datadog_checks.base.utils.subprocess_output`.

```python
from datadog_checks.base.utils.subprocess_output import get_subprocess_output
out, err, retcode = get_subprocess_output(["ls", "."], self.log, raise_on_empty_output=True)
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Cogni-AI-OU](https://github.com/Cogni-AI-OU)
- **Source:** [Cogni-AI-OU/cogni-ai-agent-skills](https://github.com/Cogni-AI-OU/cogni-ai-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cogni-ai-ou-cogni-ai-agent-skills-datadog-agent
- Seller: https://agentstack.voostack.com/s/cogni-ai-ou
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.