Agent-based integrations use the Datadog Agent to collect data, and are built around Agent checks. There are three types of checks:
An OpenMetrics check is suitable for gathering telemetry data from existing applications that expose metrics using the OpenMetrics standard.
A Python check is suitable for monitoring services or products that do not expose metrics in a standard format. Python checks can also be used to collect telemetry data from various APIs or command line tools.
DogStatsD is suitable for applications that already emit telemetry using the StatsD protocol.
Agent integrations are bi-directional; they pull data from, and push data into Datadog. This differentiates them from informational tile-only listings on the Datadog Marketplace, such as a standalone SaaS license or a professional service offering, which are not bi-directional.
Integrations send the following types of data to Datadog:
Use an API integration to enrich and submit data from your backend, or pull data directly out of Datadog. API integrations work well in building a connector between Datadog and another SaaS platform. This method is ideal for Technology Partners that are SaaS based, and have an existing website for users to log into for authorization purposes.
Since API integrations do not use the Datadog Agent to collect data, you need to create an informational tile-only listing once your development work is complete.
REST API integrations must be bi-directional, meaning that the integration should be able to pull data from and push data into Datadog.
REST API Integrations send the following types of data to Datadog:
A Datadog API key is required to submit data to a Datadog API endpoint, and an application key is required to query data from Datadog. Instead of requesting these credentials directly from a user, Datadog recommends using OAuth to handle authorization and access for API-based integrations.
You can explore examples of existing API integrations in the integrations-extras repository such as Vantage.
The Datadog Development Toolkit command expects you to be working in the $HOME/dd/ directory. This is not mandatory, but working in a different directory requires additional configuration steps.
Once you have been granted access to the Marketplace repository, create the dd directory and clone the marketplace repo:
git clone firstname.lastname@example.org:DataDog/marketplace.git
Create a feature branch to work in.
Install and configure the Datadog development toolkit
The Agent Integration Developer Tool allows you to create scaffolding when you are developing an integration by generating a skeleton of your integration tile’s assets and metadata. For instructions on installing the tool, see Install the Datadog Agent Integration Developer Tool.
After you install the Developer tool, configure it for the marketplace repo:
Set marketplace as the default working repository:
ddev config set marketplace $HOME/dd/marketplace
ddev config set repo marketplace
If you used a directory other than $HOME/dd to clone the marketplace directory, use the following command to set your working repository:
ddev config set marketplace <PATH/TO/MARKETPLACE>
ddev config set repo marketplace
Populate the integration tile scaffolding
Run the ddev command to generate a skeleton of the folders and files needed for your integration. The options you use with the command are different depending on what type of integration you are developing. For a full list of the files created by the ddev command, see Integrations assets.
Create an informational tile only listing
For Datadog Apps, Datadog REST API integrations, professional services, and standalone SaaS licenses, use the Datadog Development Toolkit to create scaffolding for an informational tile-only listing.
To create the informational tile-only listing’s scaffolding:
Make sure you’re inside the marketplace directory:
Run the ddev command with the -t tile option:
ddev create -t tile "<Offering Name>"
Create a full Agent-based integration
To generate the scaffolding for an Agent-based integration:
Make sure you’re inside the marketplace directory:
Run the ddev command:
ddev create "<Offering Name>"
Complete the necessary integration asset files
Make sure that the following required assets for your integration are complete:
Includes an Overview, Setup, Data Collected (optional), and Support section using H2 headings (##) in Markdown.
Contains a list of out-of-the-box metrics included in the integration defined in the following format ending with a comma: metric_name,metric_type,interval,unit_name,per_unit_name,description, orientation,integration,short_name,curated_metric.
Technology Partners are responsible for adding the EULA.
Once you have created a README.md file, add the following sections as H2s (##) and fill out the content that is displayed in the Marketplace tile:
Write a description under an ## Overview header that describes the value your offering provides to users and benefits to purchasing and installing the integration in the Datadog Marketplace (for example, out-of-the-box dashboards, replays of user sessions, logs, alerts, and more).
This information is displayed in the Overview tab on the integration tile.
Include all the steps to setting up your Marketplace integration that includes information divided into H3 headings (###). Standard topics include:
- Installing the integration using the in-app integration tile. - Configuring the integration with the appropriate roles and permissions in your Datadog organization. - Accessing out-of-the-box Datadog features that users who purchased and installed the integration can access (such as metrics, events, monitors, logs, dashboards, and more).
Include all the steps to uninstalling your Marketplace integration. This information is displayed in the Configure tab on the integration tile.
Specify the types of data collected by your Marketplace integration that includes information about out-of-the-box metrics, events, or service checks.
You can include additional types of data collected such as logs, monitors, dashboards, and more. If your Marketplace integration does not provide any of these, you do not need to add a Data Collected section.
Provide contact information that includes an email to your Support team, a phone number to your company, a link to your company’s documentation or blog post, and more help information in a bulleted list format.
A media carousel of images and a video is included in your integration tile.
Technology Partners can add a video to an integration tile. Do not upload the video in your pull request. Instead, send a copy or a download link of your video to email@example.com. The Marketplace team replies with a vimeo_link which you can add in the manifest.json file to include the video in the media carousel.
The video must meet the following requirements:
The maximum video size is 1GB.
The aspect ratio must be 16:9 exactly and the resolution must be 1920x1080 or higher.
The video file name must be partnerName-appName.mp4.
The maximum video length is 60 seconds.
The maximum number of characters allowed is 300.
Technology Partners can add up to eight images (seven if you are including a video) in an integration tile’s media carousel.
The images must meet the following requirements:
.jpg or .png.
The average is around 500KB. The maximum image size is 1MB.
The aspect ratio must be 16:9 exactly and fit these specifications:
Push up your feature branch and open a pull request that contains your integration tile’s asset files (including images) in the marketplace repository. The Marketplace repository does not allow forks. For instructions on creating a clone of the repo, see the Set up section. After you’ve created your pull request, automatic checks run in Azure DevOps pipelines to verify that your pull request is in good shape and contains all the required content to be updated.
To request access to the Azure DevOps pipeline, leave a comment in the pull request requesting access.
Once your pull request passes all the checks, reviewers from the Datadog/agent-integrations, Datadog/marketplace-review, and Datadog/documentation teams provide suggestions and feedback on best practices.
Once you have addressed the feedback and re-requested reviews, these reviewers approve your pull request. Contact the Marketplace team if you would like to preview the integration tile in your sandbox account. This allows you to validate and preview additional changes in the integration tile on the Datadog Marketplace before your pull request is merged.
Coordinate GTM opportunities
Once a Marketplace tile is live, Technology Partners can meet with Datadog’s Partner Marketing team to coordinate a joint go-to-market (GTM) strategy, which includes the following: