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:

AttributeMandatory or OptionalDescription
manifest_versionMandatoryType: String Enum.

Version of the manifest schema. Supported values include 1.0.0 and 2.0.0.
app_uuidMandatoryType: UUID.

Globally unique UUID for this application. This is automatically generated by Datadog when the developer toolkit ddev create command runs as part of creating tile scaffolding for your integration tile.
app_idMandatoryType: 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.
assetsMandatoryType: Dictionary.

Object containing any Datadog installable entity.
assets[dashboards]OptionalType: Dictionary.

Out-of-the-box dashboards associated with this offering.
assets[dashboards["dashboard_short_name"]]MandatoryType: 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]OptionalType: Dictionary.

Object containing information about the integration.
assets[integration[auto_install]]MandatoryType: Boolean.

Whether or not the integration and related assets should be installed automatically when metrics or logs from the integration are received from the source. This is typically set to true for integrations using the Datadog Agent, and other integrations that are configured outside the Datadog UI. It is typically set to false for marketplace integrations and integrations that are configured with the Datadog UI, such as integrations using OAuth.
assets[integration[configuration]]Mandatory, can be { }Type: Dictionary.

Object representing the configuration specification for this integration.
assets[integration[configuration[spec]]]MandatoryType: String.

Relative path to where the configuration spec lives in relation to this manifest.
assets[integration[events]]MandatoryType: Dictionary.

Information about events emitted by this integration.
assets[integration[events[creates_events]]]MandatoryType: Boolean.

Whether or not this integration emits events to Datadog.
assets[integration[metrics]]MandatoryType: Dictionary.

Information about the metrics this integration emits.
assets[integration[metrics[check]]]MandatoryType: String or list of strings.

A string or list representing metrics that this integration always emits on every run.
assets[integration[metrics[metadata_path]]]MandatoryType: String.

Relative path to where the metrics metadata lives in relation to this manifest.
assets[integration[metrics[prefix]]]MandatoryType: 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]]]MandatoryType: String.

Relative path to where the service check metadata lives in relation to this manifest.
assets[integration[source_type_name]]MandatoryType: String.

User-facing name of this integration.
assets[integration[source_type_id]]MandatoryType: Integer.

Globally unique ID for this integration. This is automatically generated by Datadog when the developer toolkit ddev create command runs as part of creating tile scaffolding for your integration tile.
assets[monitors]OptionalType: Dictionary.

Recommended monitors.
assets[monitors["monitor_short_name"]]MandatoryType: 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.
authorMandatoryType: Dictionary.

Information about the author of this app.
author[homepage]MandatoryType: String (URL).

The web URL to the homepage of the author.
author[name]MandatoryType: String.

The human-readable name for this company.
author[sales_email]MandatoryType: String (Email).

The Partner email to contact for any subscription-level events.
author[support_email]MandatoryType: String (Email).

The Partner email to contact for any support and maintenance queries.
author[contact_link]OptionalType: String (URL).

The URL link to meeting scheduling software, such as Calendly. This field is mandatory for professional services listings.
author[vendor_id]MandatoryType: 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_websiteMandatoryType: 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_termsMandatoryType: Dictionary.

Any legal documentation that a user needs to agree to in order to use this app.
legal_terms[eula]MandatoryType: String.

Relative path to the End User License Agreement (EULA) PDF in relation to this manifest.
pricingMandatoryType: 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.
tileMandatoryType: 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]]MandatoryType: String or Enum.

The type of media this is. Allowed values are image and video.
tile[media[caption]]MandatoryType: String.

The caption for the image.
tile[media[image_url]]MandatoryType: 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]MandatoryType: String[80].

A brief description of what this offering provides. Limited to 80 characters.
tile[title]MandatoryType: 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:

NameDescription
Category::AI/MLIntegrations that monitor AI and Machine Learning technologies, Large Language Models, and assist with AI/ML Operations.
Category::AlertingIntegrations that collect Datadog data to alert on, or send alerts into Datadog.
Category::AutomationIntegrations for technologies that automate processes such as security, compliance, testing, and AIOps.
Category::AWSIntegrations that send in data from Amazon Web Services and its related services.
Category::AzureIntegrations that send in data from Azure and its related services.
Category::CachingIntegrations that monitor caches and caching technologies.
Category::CloudIntegrations that submit data from cloud platforms and their related services.
Category::CollaborationIntegrations for platforms that center around communication and collaboration, such as code collaboration, messaging software, and conference calling.
Category::ComplianceIntegrations that monitor and send compliance data into Datadog, such as support for HIPPA, SOC2, GDPR, and more.
Category::Configuration & DeploymentIntegrations that monitor platforms that can configure and deploy infrastructure.
Category::ContainersIntegrations that track metrics, logs, events, and traces from containers and container management technologies.
Category::Cost ManagementIntegrations that help track and manage cloud cost.
Category::Data StoresIntegrations that monitor data storage solutions such as databases, clusters, data lakes, and more.
Category::Developer ToolsIntegrations for technologies that developers use to help build applications such as version control, CI/CD, and infrastructure as code.
Category::Event ManagementIntegrations that send events into Datadog or query events to send into external platforms.
Category::Google CloudIntegrations that send in data from Google Cloud and its related services.
Category::IncidentsIntegrations that send incidents into Datadog, or create incidents externally based on Datadog data.
Category::IoTIntegrations that monitor IoT (Internet of Things) devices.
Category::Issue TrackingIntegrations that help users identify and manage issues in their infrastructure or code.
Category::KubernetesIntegrations that send in data from Kubernetes and Kubernetes-related services.
Category::LanguagesIntegrations that send metrics and additional data based on specific programming languages.
Category::Log CollectionIntegrations that submit or query logs from Datadog.
Category::MainframesIntegrations that monitor mainframe systems such as IBM z/OS.
Category::MarketplaceIntegrations that are sold in the Datadog Marketplace for an additional fee.
Category::Message QueuesIntegrations that monitor messaging queues and messaging systems.
Category::MetricsIntegrations that submit and query metrics from Datadog.
Category::MobileIntegrations that monitor mobile devices and applications.
Category::NetworkIntegrations that monitor networks and network devices.
Category::NotificationsIntegrations for technologies that focus on notifications, for example, incident response.
Category::OracleIntegrations that monitor Oracle-based technologies.
Category::OrchestrationIntegrations for technologies that provide orchestration for containers and more.
Category::OS & SystemIntegrations that monitor operating systems or other low-level systems.
Category::ProvisioningIntegrations for technologies that manage the provisioning of resources across the cloud, containers, and more.
Category::SAPIntegrations for SAP technologies.
Category::SecurityIntegrations that monitor security tools or provide security reporting.
Category::SNMPIntegrations that monitor SNMP and related tools.
Category::Source ControlIntegrations that monitor source code collaboration tools such as Git.
Category::TestingIntegrations that monitor technologies that run browser tests, load testing, and more.
Category::TracingIntegrations that send in or query traces from Datadog, and interact with Datadog APM.
Offering::IntegrationThis is an offering that submits or queries data from a user’s Datadog account.
Offering::Professional ServiceThis 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 LicenseThis is a paid offering that provides a subscription to a SaaS product through the Datadog Marketplace.
Offering::UI ExtensionThis is a custom dashboard widget that displays a rendered, interactive iFrame on the dashboards of Datadog users.
Queried Data Type::MetricsAn integration that reads metrics from a Datadog user’s account.
Queried Data Type::LogsAn integration that reads logs from a Datadog user’s account.
Queried Data Type::TracesAn integration that reads traces from a Datadog user’s account.
Queried Data Type::EventsAn integration that reads events from a Datadog user’s account.
Queried Data Type::IncidentsAn integration that reads incidents from a Datadog user’s account.
Submitted Data Type::MetricsAn integration that sends metrics into a Datadog user’s account.
Submitted Data Type::LogsAn integration that sends logs into a Datadog user’s account.
Submitted Data Type::TracesAn integration that sends traces into a Datadog user’s account.
Submitted Data Type::EventsAn integration that sends events into a Datadog user’s account.
Submitted Data Type::IncidentsAn integration that sends incidents into a Datadog user’s account.
Supported OS::AndroidAn integration that can run on and query/submit data from Android.
Supported OS::AnyAn integration that can run on and query/submit data from any OS.
Supported OS::HP-UXAn integration that can run on and query/submit data from HP-UX.
Supported OS::IBM i/OSAn integration that can run on and query/submit data from IBM i/OS.
Supported OS::IBM z/OSAn integration that can run on and query/submit data from IBM z/OS.
Supported OS::iOSAn integration that can run on and query/submit data from iOS.
Supported OS::LinuxAn integration that can run on and query/submit data from Linux.
Supported OS::macOSAn integration that can run on and query/submit data from macOS.
Supported OS::SolarisAn integration that can run on and query/submit data from Solaris.
Supported OS::WindowsAn 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:

AttributeDescription
agent_versionMinimum Agent version supported.
integrationThe name of the integration that emits this service check. Must be the non-normalized tile.title from manifest.json.
checkName of the service check. It must be unique.
statusesList of different status of the check, to choose among ok, warning, and critical. unknown is also a possibility.
groupsTags sent with the service check.
nameDisplayed name of the service check. The displayed name must be self-explanatory and unique across all integrations.
descriptionDescription 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 nameMandatory or OptionalDescription
metric_nameMandatoryName of the metric.
metric_typeMandatoryType of the metric. For a list of available metric submission types, see Metrics Types.
intervalOptionalCollection interval of the metric in seconds.
unit_nameOptionalUnit of the metric. For a complete list of supported units, see Metrics Units.
per_unit_nameOptionalIf there is a unit sub-division, such as request per second.
descriptionOptionalDescription of the metric.
orientationMandatorySet 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.
integrationMandatoryThe 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_nameMandatoryExplicit unique ID for the metric.
curated_metricOptionalMarks 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.

Further Reading