Integration Assets Reference

Docs > Developers > Build an Integration > Integration Assets Reference

Overview

This page walks you through the files that you need to populate in order to create an offering on the Integrations page or the Marketplace page.

Configuration file

When preparing a new integration, you must include an example configuration that contains the necessary options and reasonable defaults. The example configuration file—which in this case, is located at <CHECK_NAME>/datadog_checks/<CHECK_NAME>/data/conf.yaml.example—has two top-level elements: init_config and instances.

The configuration under init_config is applied to the integration globally, and is used in every instantiation of the integration, whereas anything within instances is specific to a given instantiation.

Configuration blocks in either section take the following form:

## @<COMMAND> [- <ARGS>]
## <DESCRIPTION LINE 1>
## <DESCRIPTION LINE 2>
#
<KEY>: <VALUE>

Configuration blocks follow a few guidelines:

Descriptions must not be empty.
Always follow this format: <THIS_IS_A_PLACEHOLDER> for placeholders. For more information, see the Documentation Site’s contributing guidelines.
All required parameters are not commented by default.
All optional parameters are commented by default.
If a placeholder has a default value for an integration (like the status endpoint of an integration), it can be used instead of a generic placeholder.

`@param` specification

You can use the @param command to describe configuration blocks and provide documentation for your configuration.

@param is implemented using one of the following forms:

@param <name> - <type> - required
@param <name> - <type> - optional
@param <name> - <type> - optional - default: <defval>

Arguments:

name: The name of the parameter, such as search_string (mandatory).
type: The data type for the parameter value (mandatory). Possible values include the following: boolean, string, integer, double, float, dictionary, list*, and object*.
defval: Default value for the parameter; can be empty (optional).

list and object variables span over multiple lines and have special rules.

In a list, individual elements are not documented with the @param specification.
In an object, you can choose to either document elements individually with the @param specification or have a common top-level description following the specification of the object itself.

Optional parameters

An optional parameter must be commented by default. Before every line the parameter spans on, add # with the same indentation as the @param specification.

Block comments

You can add a block comment anywhere in the configuration file with the following rules:

Comments start with ##.
Comments should be indented like any variable (the hyphen doesn’t count).

For more information about YAML syntax, see the Wikipedia article about YAML. You can also explore the Online YAML Parser.

Manifest file

Every offering on the Integrations page or the Marketplace page contains a manifest.json file that defines operating parameters, positioning within the greater Datadog integration ecosystem, and additional metadata.

You can find the complete list of mandatory and optional attributes for the manifest.json file below:

Attribute	Mandatory or Optional	Description
`manifest_version`	Mandatory	Type: String Enum. Version of the manifest schema. Supported values include `1.0.0` and `2.0.0`.
`app_uuid`	Mandatory	Type: UUID. Globally unique UUID for this application.
`app_id`	Mandatory	Type: String. The unique identifying name of this offering. Usually kebab case of the app title. For example, if the app title is “Marketplace Offering”, then the `app_id` would be `marketplace-offering`.
`assets`	Mandatory	Type: Dictionary. Object containing any Datadog installable entity.
`assets[dashboards]`	Optional	Type: Dictionary. Out-of-the-box dashboards associated with this offering.
`assets[dashboards["dashboard_short_name"]]`	Mandatory	Type: String. Key and value pairs for any out-of-the-box dashboards. The key is the globally unique short name of the dashboard and the value is the relative path to the dashboard’s JSON definition in relation to this manifest.
`assets[integration]`	Optional	Type: Dictionary. Object containing information about the integration.
`assets[integration[configuration]]`	Mandatory, can be `{ }`	Type: Dictionary. Object representing the configuration specification for this integration.
`assets[integration[configuration[spec]]]`	Mandatory	Type: String. Relative path to where the configuration spec lives in relation to this manifest.
`assets[integration[events]]`	Mandatory	Type: Dictionary. Information about events emitted by this integration.
`assets[integration[events[creates_events]]]`	Mandatory	Type: Boolean. Whether or not this integration emits events to Datadog.
`assets[integration[metrics]]`	Mandatory	Type: Boolean. Information about the metrics this integration emits.
`assets[integration[metrics[check]]]`	Mandatory	Type: String or list of strings. A string or list representing metrics that this integration always emits on every run.
`assets[integration[metrics[metadata_path]]]`	Mandatory	Type: String. Relative path to where the metrics metadata lives in relation to this manifest.
`assets[integration[metrics[prefix]]]`	Mandatory	Type: String. The prefix for metrics emitted by this integration.
`assets[integration[service_checks]]`	Mandatory, but can be `{ }`	Type: Dictionary. Information about service checks emitted by this integration.
`assets[integration[service_checks[metadata_path]]]`	Mandatory	Type: String. Relative path to where the service check metadata lives in relation to this manifest.
`assets[integration[source_type_name]]`	Mandatory	Type: String. User-facing name of this integration.
`assets[monitors]`	Optional	Type: Dictionary. Recommended monitors.
`assets[monitors["monitor_short_name"]]`	Mandatory	Type: String. Key and value pairs for any recommended monitors. The key is the globally unique short name of the monitor and the value is the relative path to the monitor’s JSON definition in relation to this manifest.
`author`	Mandatory	Type: Dictionary. Information about the author of this app.
`author[homepage]`	Mandatory	Type: String (URL). The web URL to the homepage of the author.
`author[name]`	Mandatory	Type: String. The human-readable name for this company.
`author[sales_email]`	Mandatory	Type: String (Email). The email to contact for any subscription-level events.
`author[support_email]`	Mandatory	Type: String (Email). The email to contact for any support and maintenance queries.
`author[vendor_id]`	Mandatory	Type: String. The vendor ID to use for subscription purposes. Must be globally unique and cannot be changed. Should follow the strict standards of `app_id` where only dashes and alphabetic chars are allowed. This value is provided to Datadog Technology Partners.
`display_on_public_website`	Mandatory	Type: Boolean. Whether or not information about this listing is displayed on the public Datadog Docs site. Once this is set to `true`, it cannot be changed.
`legal_terms`	Mandatory	Type: Dictionary. Any legal documentation that a user needs to agree to in order to use this app.
`legal_terms[eula]`	Mandatory	Type: String. Relative path to the End User License Agreement (EULA) PDF in relation to this manifest.
`pricing`	Mandatory	Type: Array of Dictionaries. List of objects representing the pricing model of the integration. See the Marketplace GitHub repository for pricing details. The Marketplace GitHub repository is private, email `marketplace@datadog.com` for access.
`tile`	Mandatory	Type: Dictionary. Information about this offering.
`tile[media]`	Mandatory, can be `[ ]`	Type: Array of Dictionaries. Information about the various image and video style objects that are presented in the media gallery carousel on the listing page.
`tile[media[media_type]]`	Mandatory	Type: String or Enum. The type of media this is. Allowed values are `image` and `video`.
`tile[media[caption]]`	Mandatory	Type: String. The caption for the image.
`tile[media[image_url]]`	Mandatory	Type: String. The relative path to this image in relation to this manifest file.
`tile[classifier_tags]`	Mandatory, can be `[ ]`	Type: Array of strings. Select and use the appropriate classifiers to describe this app, including `categories`, `submitted or queried data types`, `supported_os`, and `available_offerings`. For more information, see Classifier Tags.
`tile[description]`	Mandatory	Type: String[80]. A brief description of what this offering provides. Limited to 80 characters.
`tile[title]`	Mandatory	Type: String[50]. The user-friendly title for this app.

Classifier tags

You can set multiple categories and define submitted or queried data types for the integration using the classifier_tags parameter.

You can find the complete list of classifier tags for the manifest.json file below:

Name	Description
Category::Alerting	Integrations that collect Datadog data to alert on, or send alerts into Datadog.
Category::Automation	Integrations for technologies that automate processes such as security, compliance, testing, and AIOps.
Category::AWS	Integrations that send in data from Amazon Web Services and its related services.
Category::Azure	Integrations that send in data from Azure and its related services.
Category::Caching	Integrations that monitor caches and caching technologies.
Category::Cloud	Integrations that submit data from cloud platforms and their related services.
Category::Collaboration	Integrations for platforms that center around communication and collaboration, such as code collaboration, messaging software, and conference calling.
Category::Compliance	Integrations that monitor and send compliance data into Datadog, such as support for HIPPA, SOC2, GDPR, and more.
Category::Configuration & Deployment	Integrations that monitor platforms that can configure and deploy infrastructure.
Category::Containers	Integrations that track metrics, logs, events, and traces from containers and container management technologies.
Category::Cost Management	Integrations that help track and manage cloud cost.
Category::Data Store	Integrations that monitor data storage solutions such as databases, clusters, data lakes, and more.
Category::Developer Tools	Integrations for technologies that developers use to help build applications such as version control, CI/CD, and infrastructure as code.
Category::Event Management	Integrations that send events into Datadog or query events to send into external platforms.
Category::Google Cloud	Integrations that send in data from Google Cloud and its related services.
Category::Incidents	Integrations that send incidents into Datadog, or create incidents externally based on Datadog data.
Category::IOT	Integrations that monitor IoT (Internet of Things) devices.
Category::Issue Tracking	Integrations that help users identify and manage issues in their infrastructure or code.
Category::Kubernetes	Integrations that send in data from Kubernetes and Kubernetes-related services.
Category::Languages	Integrations that send metrics and additional data based on specific programming languages.
Category::Log Collection	Integrations that submit or query logs from Datadog.
Category::Mainframe	Integrations that monitor mainframe systems such as IBM z/OS.
Category::Marketplace	Integrations that are sold in the Datadog Marketplace for an additional fee.
Category::Messaging	Integrations that monitor messaging queues and messaging systems.
Category::Metrics	Integrations that submit and query metrics from Datadog.
Category::Mobile	Integrations that monitor mobile devices and applications.
Category::Network	Integrations that monitor networks and network devices.
Category::Notification	Integrations for technologies that focus on notifications, for example, incident response.
Category::Oracle	Integrations that monitor Oracle-based technologies.
Category::Orchestration	Integrations for technologies that provide orchestration for containers and more.
Category::OS & System	Integrations that monitor operating systems or other low-level systems.
Category::Provisioning	Integrations for technologies that manage the provisioning of resources across the cloud, containers, and more.
Category::SAP	Integrations for SAP technologies.
Category::Security	Integrations that monitor security tools or provide security reporting.
Category::SNMP	Integrations that monitor SNMP and related tools.
Category::Source Control	Integrations that monitor source code collaboration tools such as Git.
Category::Testing	Integrations that monitor technologies that run browser tests, load testing, and more.
Category::Tracing	Integrations that send in or query traces from Datadog, and interact with Datadog APM.
Offering::Integration	This is an offering that submits or queries data from a user’s Datadog account.
Offering::Professional Service	This is a paid offering that provides third-party professional services, such as consulting, integration creation, and more to Datadog customers through the Datadog Marketplace.
Offering::Software License	This is a paid offering that provides a subscription to a SaaS product through the Datadog Marketplace.
Offering::UI Extension	This is a custom dashboard widget that displays a rendered, interactive iFrame on the dashboards of Datadog users.
Queried Data Type::Metrics	An integration that reads metrics from a Datadog user’s account.
Queried Data Type::Logs	An integration that reads logs from a Datadog user’s account.
Queried Data Type::Traces	An integration that reads traces from a Datadog user’s account.
Queried Data Type::Events	An integration that reads events from a Datadog user’s account.
Queried Data Type::Incidents	An integration that reads incidents from a Datadog user’s account.
Submitted Data Type::Metrics	An integration that sends metrics into a Datadog user’s account.
Submitted Data Type::Logs	An integration that sends logs into a Datadog user’s account.
Submitted Data Type::Traces	An integration that sends traces into a Datadog user’s account.
Submitted Data Type::Events	An integration that sends events into a Datadog user’s account.
Submitted Data Type::Incidents	An integration that sends incidents into a Datadog user’s account.
Supported OS::Android	An integration that can run on and query/submit data from Android.
Supported OS::Any	An integration that can run on and query/submit data from any OS.
Supported OS::HP-UX	An integration that can run on and query/submit data from HP-UX.
Supported OS::IBM i/OS	An integration that can run on and query/submit data from IBM i/OS.
Supported OS::IBM z/OS	An integration that can run on and query/submit data from IBM z/OS.
Supported OS::iOS	An integration that can run on and query/submit data from iOS.
Supported OS::Linux	An integration that can run on and query/submit data from Linux.
Supported OS::macOS	An integration that can run on and query/submit data from macOS.
Supported OS::Solaris	An integration that can run on and query/submit data from Solaris.
Supported OS::Windows	An integration that can run on and query/submit data from Windows.

Service check file

The service_check.json file describes the service checks made by the integration.

You can find the complete list of mandatory attributes for the service_checks.json file below:

Attribute	Description
`agent_version`	Minimum Agent version supported.
`integration`	The name of the integration that emits this service check. Must be the non-normalized `tile.title` from `manifest.json`.
`check`	Name of the service check. It must be unique.
`statuses`	List of different status of the check, to choose among `ok`, `warning`, and `critical`. `unknown` is also a possibility.
`groups`	Tags sent with the service check.
`name`	Displayed name of the service check. The displayed name must be self-explanatory and unique across all integrations.
`description`	Description of the service check.

Metrics metadata file

The metadata.csv file describes all of the metrics that can be collected by the integration.

You can find the complete list of mandatory and optional attributes for the metadata.csv file below:

Column name	Mandatory or Optional	Description
`metric_name`	Mandatory	Name of the metric.
`metric_type`	Mandatory	Type of the metric. For a list of available metric submission types, see Metrics Types.
`interval`	Optional	Collection interval of the metric in seconds.
`unit_name`	Optional	Unit of the metric. For a complete list of supported units, see Metrics Units.
`per_unit_name`	Optional	If there is a unit sub-division, such as `request per second`.
`description`	Optional	Description of the metric.
`orientation`	Mandatory	Set to `1` if the metric should go up, such as `myapp.turnover`. Set to `0` if the metric variations are irrelevant. Set to `-1` if the metric should go down, such as `myapp.latency`.
`integration`	Mandatory	The name of the integration that emits the metric. Must be the normalized version of the `tile.title` from the `manifest.json` file. Any character besides letters, underscores, dashes, and numbers are converted to underscores. For example: `Openstack Controller` -> `openstack_controller`, `ASP.NET` -> `asp_net`, and `CRI-o` -> `cri-o`.
`short_name`	Mandatory	Explicit unique ID for the metric.
`curated_metric`	Optional	Marks which metrics for an integration are noteworthy for a given type (`cpu` and `memory` are both accepted). These are displayed in the UI above the other integration metrics.