Managing Integrations Content
Relevant source files
The following files were used as context for generating this wiki page:
Managing content for a Datadog integration involves creating a structured collection of files that define the integration's metadata, configuration, data collection, and user-facing assets. This process ensures that integrations are discoverable, easy to set up, and provide immediate value through out-of-the-box dashboards, monitors, and clear documentation. The content is packaged to be used within the Datadog platform, whether it's a private custom check or a public integration shared with the community.
The core of integration content management lies in a set of key files, including manifest.json for metadata, conf.yaml.example for configuration, metadata.csv for metric definitions, and various asset files for dashboards and logos. Adhering to the defined structure and content guidelines is crucial for a successful submission and a positive user experience.
Sources: content/en/developers/integrations/build_integration.md, content/en/developers/integrations/check_references.md
Integration Development and Submission Workflow
The process of creating and submitting an integration to Datadog follows a series of well-defined steps, managed through the Integration Developer Platform. This workflow ensures all necessary metadata, code, and content are correctly configured before review.
The following diagram illustrates the high-level workflow for building and submitting an integration.
This diagram shows the end-to-end process for a Technology Partner to submit an integration, from initial listing creation to final review and publication.
Sources: content/en/developers/integrations/build_integration.md:11-100
Core Integration Assets
A Datadog integration is composed of several key files that define its functionality and presentation. These assets are essential for the integration to be correctly interpreted and displayed by the Datadog platform.
The diagram below shows the primary files that constitute an integration package.
This diagram illustrates the file structure of a typical integration, highlighting the purpose of each core component.
Sources: content/en/developers/integrations/check_references.md, layouts/shortcodes/integration-assets.en.md
Asset File Summary
The following table summarizes the purpose of each major file within an integration.
| File / Directory | Description |
|---|---|
manifest.json | Defines metadata, operating parameters, and positioning within the Datadog ecosystem. |
metadata.csv | Describes all metrics collected by the integration, including type, units, and description. Required for integrations sending metrics. |
conf.yaml.example | Provides an example configuration file with necessary options and reasonable defaults for users. |
service_check.json | Describes the service checks performed by the integration. |
check.py | Contains the Python code and logic for the Agent check that collects data. |
README.md | Includes an overview, setup instructions, data collected, and support information. |
assets/dashboards/ | Contains JSON files for out-of-the-box dashboards. Required for all integrations. |
assets/monitors/ | Contains JSON files for out-of-the-box monitor templates. |
assets/logos/ | Contains SVG logo files for light and dark modes. |
assets/images/ | Contains images and videos for the integration tile's media carousel. |
Changelog.md | Documents release notes and version information. |
Sources: layouts/shortcodes/integration-assets.en.md, content/en/developers/integrations/check_references.md, content/en/developers/guide/legacy.md
manifest.json
The manifest.json file is the central metadata file for an integration. It provides essential information that Datadog uses to display and categorize the integration.
| Key | Description |
|---|---|
maintainer | A contact email for the integration maintainer. |
manifest_version | The version of the manifest file format. |
name | The name of the integration. |
short_description | A brief description of the integration. |
support | Support level. For community contributions, this is contrib. |
version | The current version of the integration. |
is_public | Boolean indicating if the integration is public. |
has_logo | Boolean indicating if a logo is provided. |
type | The type of integration, typically check. |
classifier_tags | An array of tags used to categorize the integration (e.g., Category::Monitoring, Supported OS::Linux). |
Sources: content/en/developers/integrations/check_references.md:46-56, content/en/developers/guide/legacy.md:121-140
conf.yaml.example
This file serves as a template for users to configure the integration. It has two main sections: init_config for global settings and instances for each specific instance to be monitored. The file uses a special comment-based syntax to provide documentation.
init_config: Configuration applied globally to the integration.instances: A list of configurations, each specific to a given instantiation of the check.
Configuration parameters are documented using @param specifications within comments.
## @param <name> - <type> - <required|optional> [- default: <defval>]
## <DESCRIPTION>
#
<KEY>: <VALUE>
- Arguments for
@param:name: The parameter name (mandatory).type: The data type, e.g.,string,integer,list,object(mandatory).defval: A default value for optional parameters.
Sources: content/en/developers/integrations/check_references.md:16-44
metadata.csv
This file is crucial for integrations that submit metrics. It provides metadata for each metric, which the Datadog UI uses for display, graphing, and alerting.
| Column | Description |
|---|---|
metric_name | The full name of the metric (e.g., my_app.requests.total). |
metric_type | The type of metric: gauge, count, or rate. |
interval | Collection interval in seconds (optional). |
unit_name | The unit of the metric (e.g., byte, request, second). |
per_unit_name | A sub-division for the unit (e.g., second for a request unit to form request per second). |
description | A short description of what the metric represents. |
orientation | Indicates if higher or lower values are better (1, 0, or -1). |
integration | The normalized name of the integration emitting the metric. |
short_name | A human-readable, abbreviated version of the metric name. |
curated_metric | Marks noteworthy metrics for display in the UI. |
sample_tags | A comma-separated list of example tags. |
Sources: content/en/developers/integrations/check_references.md:92-113, content/en/developers/guide/legacy.md:144-206, content/en/developers/integrations/build_integration.md:54-64
service_check.json
This file defines the service checks that the integration can emit, which report on the status of a monitored service (e.g., OK, WARNING, CRITICAL).
| Attribute | Description |
|---|---|
agent_version | Minimum Agent version supported. |
integration | The name of the integration emitting the check. |
check | The unique name of the service check. |
statuses | A list of possible statuses, such as ok, warning, critical. |
groups | Tags sent with the service check. |
name | The display name for the service check. |
description | A description of what the service check monitors. |
Sources: content/en/developers/integrations/check_references.md:58-73, content/en/developers/guide/legacy.md:90-91
Out-of-the-Box Content
To enhance user experience, integrations must include ready-to-use content. Dashboards are a mandatory component for all integrations.
Dashboards
Out-of-the-box dashboards provide users with immediate visibility into the data collected by the integration.
The process for creating and including a dashboard is as follows:
This diagram outlines the steps to create a dashboard, export it, and add it to an integration package.
Key Requirements & Best Practices:
- At least one dashboard is required for all integrations.
- The dashboard title should include the integration name.
- An "About" group should provide a description and helpful links.
- An "Overview" group should display the most important metrics at the top.
- Use a mix of widget types and ensure the layout is symmetrical and responsive.
- Template variables should be used to allow dynamic filtering.
Sources: content/en/developers/integrations/create-an-integration-dashboard.md:17-152, content/en/developers/integrations/build_integration.md:78-81
Other Content
In addition to dashboards, integrations can include other valuable assets:
- Monitors: Pre-configured monitor templates to help users set up alerts.
- SIEM Detection Rules: Rules for security-focused integrations.
- Log Pipelines: Required if the integration sends logs, to parse and enrich log data.
- Logos: SVG files for branding in the Datadog UI.
Sources: content/en/developers/integrations/build_integration.md:66-87, layouts/shortcodes/integration-assets.en.md:20-30
Conclusion
Managing content for a Datadog integration is a systematic process centered around a collection of structured files and assets. By carefully crafting the manifest.json, metadata.csv, configuration files, and out-of-the-box content like dashboards, developers can create robust, user-friendly integrations. This structured approach not only facilitates the review and publication process but also ensures that end-users can quickly and effectively leverage the integration to monitor their systems within the Datadog platform.
Sources: content/en/developers/integrations/build_integration.md, content/en/developers/integrations/check_references.md