Develop a Marketplace Offering

Overview

This page walks you through how to develop an offering on the Datadog Marketplace. If you have any questions, reach out to marketplace@datadoghq.com.

Development process

To develop a Marketplace tile, follow these instructions:

  1. Choose a type of offering to list.
  2. Access the Marketplace repository and set up a directory.
  3. Install and configure the Datadog Development Toolkit.
  4. Populate the integration tile scaffolding.
  5. Complete the necessary integration asset files.
  6. Open a pull request.
  7. Review feedback and request approval to merge the pull request and release the integration tile.
  8. Coordinate go-to-market opportunities with Partner Marketing.

Select an offering

A standard Marketplace integration tile appears with the following format:

Example Marketplace tile

Choose from the following offering types to create an integration tile that represents your listing on the Datadog Marketplace:

Agent-based integrations

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:

For more information about Datadog Agent-based integrations, see:

REST API integrations

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.

Datadog Apps

Datadog Apps are custom dashboard widgets that are developed in the Datadog Developer Platform. Once your Datadog App is ready to publish, you need to create an informational tile-only listing on the Integrations or Marketplace page.

SaaS license or professional service offerings

To list a SaaS license or professional service offering in the Marketplace, you only need to create an informational tile-only listing.

Set up a directory and clone the Marketplace repository

Once you’ve decided on an offering, set up a directory:

  1. Request access to the Marketplace repository by following the instructions in the Marketplace documentation.

  2. Create a dd directory:

    mkdir $HOME/dd

    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.

  3. Once you have been granted access to the Marketplace repository, create the dd directory and clone the marketplace repo:

    git clone git@github.com:DataDog/marketplace.git

  4. Create a feature branch to work in.

Install and configure the Datadog development toolkit

The Datadog Development Toolkit command (ddev) allows you to create scaffolding when you are developing an integration by generating a skeleton of your integration tile’s assets and metadata.

Before you begin, make sure you meet the following prerequisites:

  • Python v3.8 or later
  • Docker is required if you’re building an Agent-based integration
  • A Python virtual environment is recommended to avoid potential environment conflicts. The instructions below use venv, which comes packaged with Python v3.3 and later on most operating systems.

Install and configure the development toolkit:

  1. Make sure you’re inside the marketplace directory:

    cd $HOME/dd/marketplace

  2. Set up a Python virtual environment:

       python3 -m venv venv
       . venv/bin/activate

    You can exit the virtual environment at any time by running deactivate.

  3. Install the Developer Toolkit:

    pip3 install "datadog-checks-dev[cli]"

    If you are using the Z Shell, you may need to use escaped characters by running pip3 install datadog-checks-dev\[cli\].

  4. 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:

  1. Make sure you’re inside the marketplace directory:
    cd $HOME/dd/marketplace
  2. 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:

  1. Make sure you’re inside the marketplace directory:
    cd $HOME/dd/marketplace
  2. Run the ddev command with the -t tile option
    ddev create "<Offering Name>"

Complete the necessary integration asset files

Make sure that the following required assets for your integration are complete:

Asset NameAsset Description
READMEIncludes an Overview, Setup, Data Collected (optional), and Support section using H2 headings (##) in Markdown.

For more information, see README.
MediaAdd any images and a video that you want to use for the integration tile’s media carousel in an images folder. You can add one video to each listing.

Technology Partners can use .png files instead of .jpg files to reduce image compression.
Media CarouselDefine the images you want to add to the integration tile’s media carousel in the media object specified in the tile front matter on the manifest.json file.

For more information, see Media Carousel.
Manifest.jsonSpecify a JSON object that includes elements such as manifest_version,
display_on_public_website, tile, author, oauth, pricing, assets, and more.

For more information, see Manifest file.
Metadata.csvContains 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.

For more information, see Metrics metadata file.
Dashboards and MonitorsProvide the JSON files for out-of-the-box dashboards and monitors included in the integration in the dashboards and monitors folders nested in the assets directory.

For both dashboards and monitors, a title and description is required.

Technology Partners can create dashboards and monitors in a provisioned sandbox account, and export these assets into JSON files. For more information about dashboards, see Best Practices for Integration Preset Dashboards.
LogosAdd at least one SVG file which can be used in light and dark modes in a logos folder nested in the assets directory, or add the file(s) directly to the assets directory.

Technology Partners are responsible for the licensing of submitted logos.
ChangelogDocument release notes and version information in the Changelog.md file using the following format: 1.0.0 / YYYY-MM-DD. This information is displayed in the Release Notes tab of the integration tile.

Technology Partners can add releases and version updates in descending order (latest version at the top).
CODEOWNERSThe CODEOWNERS file belongs in the shared .github directory and defines the individuals or teams responsible for maintaining the content and source code in the Marketplace repository.

For more information about syntax, see the GitHub code owners documentation.
End User License Agreement (EULA)Add the eula.pdf file in the assets directory.

Technology Partners are responsible for adding the EULA.

README

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:

Header NameHeader
OverviewWrite 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.
SetupInclude 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).
UninstallationInclude all the steps to uninstalling your Marketplace integration. This information is displayed in the Configure tab on the integration tile.
Data CollectedSpecify 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.
SupportProvide 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 marketplace@datadoghq.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:

Video RequirementsDescription
TypeMP4 H.264
SizeThe maximum video size is 1GB.
DimensionsThe aspect ratio must be 16:9 exactly and the resolution must be 1920x1080 or higher.
NameThe video file name must be partnerName-appName.mp4.
Video LengthThe maximum video length is 60 seconds.
DescriptionThe 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:

Image RequirementsDescription
Type.jpg or .png.
SizeThe average is around 500KB. The maximum image size is 1MB.
DimensionsThe aspect ratio must be 16:9 exactly and fit these specifications:

- Width: 1440px
- Minimum height: 810px
- Maximum height: 2560px
NameUse letters, numbers, underscores, and hyphens. Do not use spaces.
Color ModeRGB
Color ProfilesRGB
DescriptionThe maximum number of characters allowed is 300.

Follow this template to define the media object in the media carousel which includes an image, a video thumbnail, and a video:

manifest.json

"media": [
      {
        "media_type": "image",
        "caption": "A Datadog Marketplace Integration OOTB Dashboard",
        "image_url": "images/integration_name_image_name.png"
      },
      {
        "media_type": "video",
        "caption": "A Datadog Marketplace Integration Overview Video",
        "image_url": "images/integration_name_video_thumbnail.png",
        "vimeo_id": 123456789
      },
    ],

For more information, see Integrations Assets Reference.

Open a pull request

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.

Review process

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:

  • A Datadog quote for partner press releases
  • A blog post on the Datadog Monitor
  • Amplification of social media posts

Further Reading