---
title: Introduction to Integrations
description: >-
  Unify metrics and logs from infrastructure using Agent-based,
  authentication-based, and library integrations.
breadcrumbs: Docs > Getting Started > Introduction to Integrations
---

# Introduction to Integrations

## Overview{% #overview %}

This is a guide for using integrations. If you are looking for information about building a new integration, see the [Create a new integration](https://docs.datadoghq.com/extend/integrations/agent_integration/) page.

An integration, at the highest level, is when you assemble a unified system from units that are usually considered separately. At Datadog, you can use integrations to bring together all of the metrics and logs from your infrastructure and gain insight into the unified system as a whole—you can see pieces individually and also how individual pieces are impacting the whole.

**Note**: It's best to start collecting metrics on your projects as early in the development process as possible, but you can start at any stage.

Datadog provides three main types of integrations:

- **Agent-based** integrations are installed with the Datadog Agent and use a Python class method called `check` to define the metrics to collect.
- **Authentication (crawler) based** integrations are set up in [Datadog](https://app.datadoghq.com/account/settings) where you provide credentials for obtaining metrics with the API. These include popular integrations like [Slack](https://docs.datadoghq.com/integrations/slack/), [AWS](https://docs.datadoghq.com/integrations/amazon_web_services/), [Azure](https://docs.datadoghq.com/integrations/azure/), and [PagerDuty](https://docs.datadoghq.com/integrations/pagerduty/).
- **Library** integrations use the [Datadog API](https://docs.datadoghq.com/api/) to allow you to monitor applications based on the language they are written in, like [Node.js](https://docs.datadoghq.com/integrations/node/) or [Python](https://docs.datadoghq.com/integrations/python/).

You can also build a [custom check](https://docs.datadoghq.com/extend/custom_checks/write_agent_check/) to define and send metrics to Datadog from your unique in-house system.

## Setting up an integration{% #setting-up-an-integration %}

The Datadog Agent package includes integrations officially supported by Datadog, in [integrations core](https://github.com/DataDog/integrations-core). To use those integrations, download the Datadog Agent. Community-based integrations are in [integrations extras](https://github.com/DataDog/integrations-extras). For more information on installing or managing these integrations, see the [integrations management guide](https://docs.datadoghq.com/agent/guide/integration-management/).

### Permissions{% #permissions %}

The Integrations Manage permission is required to interact with an Integration tile. See [RBAC roles](https://docs.datadoghq.com/account_management/rbac/permissions/#integrations) for more information.

### API and application keys{% #api-and-application-keys %}

To [install the Datadog Agent](https://app.datadoghq.com/account/settings/agent/latest), you need an [API key](https://docs.datadoghq.com/account_management/api-app-keys/). If the Agent is already downloaded, make sure to set up the API key in the `datadog.yaml` file. To use most additional Datadog functionality besides submitting metrics and events, you need an [application key](https://docs.datadoghq.com/account_management/api-app-keys/). You can manage your accounts API and application keys in the [API Settings page](https://app.datadoghq.com/organization-settings/api-keys).

### Installation{% #installation %}

If you want to connect with a crawler or library based integration, navigate to that provider on the [Integrations page](https://docs.datadoghq.com/integrations/) for specific instructions on how to connect. For other supported integrations, install the [Datadog Agent](https://app.datadoghq.com/account/settings/agent/latest). Most integrations are supported for the containerized Agents: [Docker](https://app.datadoghq.com/account/settings/agent/latest?platform=docker) and [Kubernetes](https://app.datadoghq.com/account/settings/agent/latest?platform=kubernetes). After you've downloaded the Agent, go to the [Integrations page](https://docs.datadoghq.com/integrations/) to find specific configuration instructions for individual integrations.

### Configuring Agent integrations{% #configuring-agent-integrations %}

Most configuration parameters are specific to the [individual integration](https://docs.datadoghq.com/integrations/). Configure Agent integrations by navigating to the `conf.d` folder at the root of your Agent's configuration directory. Each integration has a folder named `<INTEGRATION_NAME>.d`, which contains the file `conf.yaml.example`. This example file lists all available configuration options for the particular integration.

To activate a given integration:

1. Rename the `conf.yaml.example` file (in the corresponding `<INTEGRATION_NAME>.d` folder) to `conf.yaml`.
1. Update the required parameters inside the newly created configuration file with the values corresponding to your environment.
1. [Restart the Datadog Agent](https://docs.datadoghq.com/agent/guide/agent-commands/#restart-the-agent).

**Note**: All configuration files follow the format documented under [@param specification](https://docs.datadoghq.com/extend/integrations/check_references/#param-specification).

For example, this is the minimum `conf.yaml` configuration file needed to collect metrics and logs from the [apache integration](https://github.com/DataDog/integrations-core/blob/master/apache/datadog_checks/apache/data/conf.yaml.example):

```yaml
init_config:
  service: apache

instances:
    - apache_status_url: http://localhost/server-status?auto

logs:
    - type: file
      path: /var/log/apache2/access.log
      source: apache
      sourcecategory: http_web_access
    - type: file
      path: /var/log/apache2/error.log
      source: apache
      sourcecategory: http_web_access
```

To monitor multiple Apache instances in the same Agent check, add additional instances to the `instances` section:

```yaml
init_config:

instances:
    - apache_status_url: "http://localhost/server-status?auto"
      service: local-apache

    - apache_status_url: "http://<REMOTE_APACHE_ENDPOINT>/server-status?auto"
      service: remote-apache
```

#### Collection interval{% #collection-interval %}

The default collection interval for all Datadog standard integrations is 15 seconds. To change the collection interval, use the parameter `min_collection_interval`. For more details, see [Updating the collection interval](https://docs.datadoghq.com/extend/custom_checks/write_agent_check/#updating-the-collection-interval).

### Tagging{% #tagging %}

Tagging is a key part of filtering and aggregating the data coming into Datadog across many sources. For more information about tagging, see [Getting started with tags](https://docs.datadoghq.com/getting_started/tagging/).

If you define tags in the `datadog.yaml` file, the tags are applied to all of your integrations data. Once you've defined a tag in `datadog.yaml`, all new integrations inherit it.

For example, setting `service` in your config file is the recommended [Agent setup](https://docs.datadoghq.com/getting_started/agent/#setup) for monitoring separate, independent systems.

To better unify your environment, it is also recommended to configure the `env` tag in the Agent. To learn more, see [Unified Service Tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/).

#### Per-check tag configuration{% #per-check-tag-configuration %}

You can customize tag behavior for individual checks, overriding the global Agent-level settings:

1. **Disable Autodiscovery tags**

By default, the metrics reported by integrations include tags automatically detected from the environment. For example, the metrics reported by a Redis check that runs inside a container include tags associated with the container, such as `image_name`. You can turn this behavior off by setting the `ignore_autodiscovery_tags` parameter to `true`.

1. **Set tag cardinality per integration check**

You can define the level of tag cardinality (low, orchestrator, or high) on a per-check basis using the `check_tag_cardinality` parameter. This overrides the global tag cardinality setting defined in the Agent configuration.

```yaml
init_config:
# Ignores tags coming from autodiscovery
ignore_autodiscovery_tags: true

# Override global tag cardinality setting
check_tag_cardinality: low

# Rest of the config here
```

For containerized environments, you can also set these parameters through [Kubernetes Autodiscovery annotations](https://docs.datadoghq.com/containers/kubernetes/integrations/#tag-cardinality).

### Validation{% #validation %}

To validate your Agent and integrations configuration, [run the Agent's `status` subcommand](https://docs.datadoghq.com/agent/guide/agent-commands/#agent-status-and-information), and look for new configuration under the Checks section.

## Installing multiple integrations{% #installing-multiple-integrations %}

Installing more than one integration is a matter of adding the configuration information to a new `conf.yaml` file in the corresponding `<INTEGRATIONS>.d` folder. Look up the required parameters for the new integration from the `conf.yaml.example` file, add it into the new `conf.yaml` file, and then follow the same steps to validate your configuration.

## Autodetected integrations{% #autodetected-integrations %}

If you set up [process collection](https://docs.datadoghq.com/infrastructure/process/), Datadog autodetects technologies running on your hosts. This identifies Datadog integrations that can help you monitor these technologies. These auto-detected integrations are displayed in the [Integrations search](https://app.datadoghq.com/account/settings):

{% image
   source="https://datadog-docs.imgix.net/images/getting_started/integrations/ad_integrations_1.49b95c9ec5e558552a4e97e4f567604f.png?auto=format"
   alt="Autodetected integrations" /%}

Each integration has one of four status types:

- **Detected**: The technology is running on a host, but the integration has not been installed or configured and only partial metrics are being collected. Configure the integration for full coverage. To find a list of hosts that are running an autodetected technology, open the integrations tile and select the **Hosts** tab.
- **Installed**: This integration is installed and configured on a host.
- **Available**: All integrations that do not fall into the **Installed** and **Detected** categories.
- **Missing Data**: Integration metrics have not been detected in the last 24 hours.

## Security practices{% #security-practices %}

For information on how Datadog handles your data, and other security considerations, see the [Security documentation](https://docs.datadoghq.com/data_security/).

## Granular access control{% #granular-access-control %}

By default, access to integration resources (accounts, services, webhooks) is unrestricted. Granular access controls can be used to restrict the behavior of users, teams, roles, or your full organization at the integration resource level.

**Note**: The restricted access option is only visible if the integration supports granular access control. To verify if granular access control is supported for an integration, review that [integration's documentation](https://docs.datadoghq.com/integrations/).

{% image
   source="https://datadog-docs.imgix.net/images/getting_started/integrations/GRACE%20integration-account-modal.7066a8aa36d484eac45e42f9fd90fb5c.png?auto=format"
   alt="Granular access controls" /%}



1. While viewing an integration, navigate to the **Configure** tab and locate the resource (account, service, webhook) that should have granular access controls applied.
1. Click **Set Permissions**.
1. By default, everyone in your org has full access. Click **Restrict Access**.
1. The dialog box updates to show that members of your organization have **Viewer** access by default.
1. Use the dropdown to select one or more teams, roles, or users that may edit the monitor. **Note**: The [Integrations Manage](https://docs.datadoghq.com/account_management/rbac/permissions/#integrations) permission is also required to edit individual resources.
1. Click **Add**.
1. The dialog box updates to show the updated permissions.
1. Click **Save**. The integration page automatically refreshes with updated permissions.

**Note:** To maintain edit access to the resource, the system requires you to include at least one role or team that you are a member of before saving.

To restore general access to a integration resource with restricted access, follow the steps below:

1. While viewing an integration, navigate to the **Configure** tab and locate the resource (account, service, webhook) that should have general access restored.
1. Click **Set Permissions**.
1. Click **Restore Full Access**.
1. Click **Save**. The integration page automatically refreshes with updated permissions.

## What's next?{% #whats-next %}

After your first integration is set up, [explore all of the metrics](https://docs.datadoghq.com/metrics/explorer/) being sent to Datadog by your application, and use these metrics to begin setting up [dashboards](https://docs.datadoghq.com/dashboards/) and [alerts](https://docs.datadoghq.com/monitors/) to monitor your data.

Also check out Datadog [Logs management](https://docs.datadoghq.com/logs/), [APM](https://docs.datadoghq.com/tracing/), and [Synthetic Monitoring](https://docs.datadoghq.com/synthetics/) solutions.

## Troubleshooting{% #troubleshooting %}

The first step to troubleshooting an integration is to use a plugin in your code editor or use one of the many online tools to verify that the YAML is valid. The next step is to run through all of the [Agent troubleshooting](https://docs.datadoghq.com/agent/troubleshooting/) steps.

If you continue to have problems, contact [Datadog support](https://docs.datadoghq.com/help/).

## Key terms{% #key-terms %}

{% dl %}

{% dt %}
`conf.yaml`
{% /dt %}

{% dd %}
You create the `conf.yaml` in the `conf.d/<INTEGRATION_NAME>.d` folder at the root of your [Agent's configuration directory](https://docs.datadoghq.com/agent/guide/agent-configuration-files/#agent-configuration-directory). Use this file to connect integrations to your system, as well as configure their settings.
{% /dd %}

{% dt %}
custom check
{% /dt %}

{% dd %}
If you have a unique system that you want to monitor, or if you're going to expand the metrics already sent by an integration, you can build a [custom check](https://docs.datadoghq.com/extend/custom_checks/write_agent_check/) to define and send metrics to Datadog. However, if you want to monitor a generally available application, public service, or an open source project and the integration doesn't exist, consider [building a new integration](https://docs.datadoghq.com/extend/integrations/agent_integration/) instead of a custom check.
{% /dd %}

{% dt %}
`datadog.yaml`
{% /dt %}

{% dd %}
This is the main configuration file where you're defining how the Agent as a whole interacts with its own integrations and with your system. Use this file to update API keys, proxies, host tags, and other global settings.
{% /dd %}

{% dt %}
event
{% /dt %}

{% dd %}
Events are informational messages about your system that are consumed by [the events explorer](https://app.datadoghq.com/event/explorer) so that you can build monitors on them.
{% /dd %}

{% dt %}
instance
{% /dt %}

{% dd %}
You define and map the instance of whatever you are monitoring in the `conf.yaml` file. For example, in the [`http_check` integration](https://github.com/DataDog/integrations-core/blob/master/http_check/datadog_checks/http_check/data/conf.yaml.example#L13), you're defining the name associated with the instance of the HTTP endpoint you are monitoring up and downtime. You can monitor **multiple instances** in the same integration, and you do that by defining all of the instances in the `conf.yaml` file.
{% /dd %}

{% dt %}
`<INTEGRATION_NAME>.d`
{% /dt %}

{% dd %}
If you have a complex configuration, you can break it down into multiple `YAML` files, and then store them all in the `<INTEGRATION_NAME>.d` folder to define the configuration. The Agent loads any valid `YAML` file in the `<INTEGRATION_NAME>.d` folder.
{% /dd %}

{% dt %}
logging
{% /dt %}

{% dd %}
If the system you are monitoring has logs, customize the logs you are sending to Datadog by using the [Log Management solution](https://docs.datadoghq.com/logs/).
{% /dd %}

{% dt %}
`metadata.csv`
{% /dt %}

{% dd %}
The file that lists and stores the metrics collected by each integration.
{% /dd %}

{% dt %}
metrics
{% /dt %}

{% dd %}
The list of what is collected from your system by each integration. You can find the metrics for each integration in that integration's `metadata.csv` file. For more information about metrics, see the [Metrics](https://docs.datadoghq.com/metrics/) developer page. You can also set up [custom metrics](https://docs.datadoghq.com/metrics/custom_metrics/), so if the integration doesn't offer a metric out of the box, you can usually add it.
{% /dd %}

{% dt %}
parameters
{% /dt %}

{% dd %}
Use the parameters in the `conf.yaml` file to control accesses between your integration data source and the Agent. The individual integrations `conf.yaml.example` file has all of the required and not required parameters listed.
{% /dd %}

{% dt %}
service check
{% /dt %}

{% dd %}
Service checks are a type of monitor used to track the uptime status of the service. For more information, see the [Service checks guide](https://docs.datadoghq.com/monitors/guide/visualize-your-service-check-in-the-datadog-ui/).
{% /dd %}

{% dt %}
tagging
{% /dt %}

{% dd %}
[Tags](https://docs.datadoghq.com/getting_started/tagging/) are a way to add customization to metrics so that you can filter and visualize them in the most useful way to you.
{% /dd %}

{% /dl %}

## Further Reading{% #further-reading %}

- [Introduction to Integrations](https://learn.datadoghq.com/courses/intro-to-integrations)
- [See a list of Datadog integrations](https://docs.datadoghq.com/integrations/)
- [Scaling Datadog observability: 1,000 integrations and counting](https://www.datadoghq.com/blog/1k-integrations-milestone/)