Datadog
Port's Datadog integration allows you to model Datadog resources in Port and ingest data into them.
Core support
SLO History, Service Metric, Service Dependency and Catalog Entity resources are not collected out of the box.
Follow the examples here to configure blueprints and resource mappings.
Setup
Choose your preferred installation method below. Not sure which to pick? See the installation methods overview.
The prerequisites required for installation are listed below.
- Go to the Datadog Connectors page in your portal.
- Under
Select your installation method, chooseHosted by Port. - Click
Connectto authorize Port via OAuth and install the integration.
Before clickingConnect, you can customize settings underAdvanced configuration(see below for details).
Advanced configuration
- During the installation process each integration may have additional settings under the
Advanced configurationsection in Port's UI. Additionally, each integration has one or more settings that can be configured after installation. To do so, click on the integration's name in the Connectors page and navigate to theSettingtab. Hover over the ⓘ icon next to each setting to see more details about it.
Port source IP addresses
When using this installation method, Port will make outbound calls to your 3rd-party applications from static IP addresses. You may need to add these addresses to your allowlist, in order to allow Port to interact with the integrated service:
- Europe (EU):
54.73.167.226,63.33.143.237,54.76.185.219 - United States (US):
3.234.37.33,54.225.172.136,3.225.234.99
Answers to common questions about OAuth integrations can be found here:
OAuth integrations FAQ
The access level of the user who authorizes the connection determines the data Port can fetch:
- With admin-level access, Port can fetch all project data.
- With restricted access, Port can fetch only the data available to that user.
Token-Based Installation requires users to manually generate and provide tokens, offering control over permissions but increasing the risk of setup errors. OAuth2 Installation automates the process, simplifying setup and reducing errors while aligning access levels with the user's permissions.
There is no limit to the number of OAuth connections you can create for integrations or organizations.
The provider displays the exact permissions when you connect it. Port requests read and write access so the resulting secrets can also support self-service actions, such as creating Jira tickets.
OAuth tokens are refreshed automatically by Port, including before manual syncs. If you encounter an HTTP 401 unauthorized error, try running a manual resync or wait for the next scheduled sync, and the issue will resolve itself. If the error persists, please contact our support team.
- Deleting an OAuth2-based installation will not revoke access to the third-party service.
- Port will delete the OAuth secret, which prevents it from utilizing the connection for future syncs.
- If you reinstall the integration, you will need to reconnect OAuth.
- Actions relying on the deleted secret (e.g., creating a Jira ticket) will fail until the secret is recreated or the integration is reinstalled.
Yes — after you authorize the integration in the Port UI, import it with terraform import and set installation_type = "SaasOAuth2". Terraform cannot create OAuth installs. You can manage mappings (config) and optional appSpec toggles; OAuth credentials (integrationSpec) stay Port-managed. See Manage integrations.
-
Go to the Datadog Connectors page in your portal.
-
Select the
Self-hostedmethod. -
A
helmcommand will be displayed, with default values already filled out (e.g. your Port client ID, client secret, etc). Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.
Scalable mode for large integrations
If you are deploying the integration at scale and want to decouple the resync process from the live events process (recommended for large or high-throughput environments), you can enable scalable mode by adding the following flags to your Helm install command:
--set workload.kind="CronJob" \
--set workload.cron.resyncTimeoutMinutes=60 \
--set scheduledResyncInterval="'*/60 * * * *'" \
--set liveEvents.worker.enabled=true
Required parameters:
port.clientId- Your port client id.port.clientSecret- Your port client secret.port.baseUrl- Your Port API URL -https://api.port.iofor EU,https://api.us.port.iofor US.integration.secrets.datadogApiKey- Datadog API key, docs can be found here.integration.secrets.datadogApplicationKey- Datadog application key, docs can be found here.integration.config.datadogBaseUrl- The base Datadog host. Defaults to https://api.datadoghq.com. If in EU, use https://api.datadoghq.eu.integration.eventListener.type- The event listener type. Read more about event listeners.integration.type- The integration to be installed.
Optional parameters (click to expand)
integration.secrets.webhookSecret- Webhook secret for authenticating incoming events. Learn more.liveEvents.baseUrl- The base url of the instance where the Datadog integration is hosted, used for real-time updates. (e.g.https://mydatadogeoceanintegration.com).integration.config.monitorNotificationRuleScope- Scope of the monitor notification rule. Only monitors matching this scope will send live events to Port. Defaults toservice:*(all service monitors). Example:service:my-service AND env:prod.integration.config.skipWebhookCreation- Default false. When set to true, the integration will not create the Datadog webhook or the monitor notification rule on startup. Set this to true if the integration's application key is read-only and you configure both objects manually in Datadog. The integration continues to receive and process live events either way. See live events setup.integration.config.appHost(deprecated) - The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Datadog.scheduledResyncInterval- The number of minutes between each resync. When not set the integration will resync for each event listener resync event.initializePortResources- Default true, When set to true the integration will create default blueprints and the port App config Mapping.sendRawDataExamples- Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true.
If you're running high volumes of live events in a self-hosted deployment and want better reliability, event durability, or horizontal scalability, you can optionally set up Port's dedicated live events infrastructure. See live events at scale for details.
Recommended resource sizes
To ensure optimal performance and avoid out-of-memory (OOM) errors, we recommend the following resources for this integration:
- CPU Limit:
800m - CPU Request:
100m - Memory Limit:
1Gi - Memory Request:
1Gi
Set resource values
helm install my-integration port-labs/port-ocean \
# ... other parameters
--set resources.limits.cpu=800m \
--set resources.limits.memory=1Gi \
--set resources.requests.cpu=100m \
--set resources.requests.memory=1Gi
- GitHub
- Jenkins
- Azure DevOps
- GitLab
- Go to the Datadog Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitHub Actions secret |
|---|---|---|---|
port_client_id | Your Port client ID (How to get the credentials). | ✓ | ✓ |
port_client_secret | Your Port client secret (How to get the credentials). | ✓ | ✓ |
port_base_url | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
datadog_base_url | US: https://api.datadoghq.com EU: https://api.datadoghq.eu. | ✓ | ✓ |
datadog_api_key | Datadog API key, docs can be found here. | ✓ | ✓ |
datadog_application_key | Datadog application key, docs can be found here. | ✓ | ✓ |
initialize_port_resources | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
integration_identifier | The identifier of the integration that will be installed. | ✗ | ✗ |
send_raw_data_examples | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Your Jenkins agent must be able to run Docker commands.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a Jenkins credential (Secret Text) |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | US: https://api.datadoghq.com EU: https://api.datadoghq.eu. | ✓ | ✓ |
OCEAN__ | Datadog API key, docs can be found here. | ✓ | ✓ |
OCEAN__ | Datadog application key, docs can be found here. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a Jenkinsfile pipeline file:Jenkins pipeline (click to expand)
Prerequisites
- Your Azure Devops agent should be able to run docker commands. Learn more about agents here.
- You must have permissions to create and manage Azure DevOps variable groups for storing credentials.
Set up your credentials
- Create a Variable Group: Name it port-ocean-credentials.
- Store the required variables (see the table below).
- Authorize Your Pipeline:
-
Go to "Library" -> "Variable groups."
-
Find port-ocean-credentials and click on it.
-
Select "Pipeline Permissions" and add your pipeline to the authorized list.
-
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as an Azure DevOps pipeline variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | US: https://api.datadoghq.com EU: https://api.datadoghq.eu. | ✓ | ✓ |
OCEAN__ | Datadog API key, docs can be found here. | ✓ | ✓ |
OCEAN__ | Datadog application key, docs can be found here. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
Here is an example for a azure-pipeline.yml pipeline file:Azure pipeline (click to expand)
- Go to the Datadog Connectors page in your portal.
- Under Select your installation method, choose your desired CI/CD platform.
- Copy the workflow and replace the placeholders with your values.
Below are the available parameters and their descriptions.
| Parameter | Description | Required? | Secret?Store this value as a GitLab CI/CD variable |
|---|---|---|---|
OCEAN__ | Your Port client ID (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port client secret (How to get the credentials). | ✓ | ✓ |
OCEAN__ | Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US). | ✓ | ✗ |
OCEAN__ | US: https://api.datadoghq.com EU: https://api.datadoghq.eu. | ✓ | ✓ |
OCEAN__ | Datadog API key, docs can be found here. | ✓ | ✓ |
OCEAN__ | Datadog application key, docs can be found here. | ✓ | ✓ |
OCEAN__ | Default true. When set to true, the integration will create default blueprints and the Port app config mapping. | ✗ | ✗ |
OCEAN__ | The identifier of the integration that will be installed. | ✗ | ✗ |
OCEAN__ | Enable sending raw data examples from the third-party API to Port for testing and managing the integration mapping. Default is true. | ✗ | ✗ |
The Datadog integration can ingest data from multiple Datadog organizations using a single installation, so you don't need to install the integration separately for each organization.
Multi-org ingestion is available for self-hosted installations only.
To enable it, provide the datadogCredentialMap parameter. When datadogCredentialMap is set, the integration fetches resources from every organization listed in it, and the single-org datadogApiKey and datadogApplicationKey parameters will be ignored.
datadogCredentialMap is a sensitive JSON array string, with one entry per organization. Each entry accepts the following keys:
| Key | Required | Description |
|---|---|---|
datadogApiKey | ✅ | The Datadog API key for the organization. Docs can be found here. |
datadogApplicationKey | ✅ | The Datadog application key for the organization. Docs can be found here. |
datadogBaseUrl | ❌ | The base Datadog host for the organization, used when the org lives on a different Datadog site. When omitted, it falls back to the integration's datadogBaseUrl. |
datadogOrgName | ❌ | The name of the Datadog organization these credentials belong to. When omitted, the integration resolves it automatically from the Datadog API, which requires the org_management permission on the application key. |
datadogOrgPublicId | ❌ | The public ID of the Datadog organization these credentials belong to. When omitted, the integration resolves it automatically from the Datadog API, which requires the org_management permission on the application key. |
For a Helm installation, pass the credential map as a secret through a values.yaml file. The example below configures a single organization, but you can add an entry to the datadogCredentialMap array for each additional organization:
values.yaml (click to expand)
port:
clientId: ""
clientSecret: ""
baseUrl: "https://api.port.io"
initializePortResources: true
sendRawDataExamples: true
scheduledResyncInterval: 360
integration:
identifier: "datadog-multi-org"
type: "datadog"
eventListener:
type: "POLLING"
secrets:
datadogCredentialMap: '[{"datadogApiKey":"","datadogApplicationKey":"","datadogBaseUrl":"https://api.datadoghq.com"}]'
Once your values.yaml file is ready, install the Datadog integration using its parameters:
helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install datadog port-labs/port-ocean -f values.yaml
- When an entry omits both
datadogOrgNameanddatadogOrgPublicId, the integration resolves the organization's identity from the Datadog API on startup. This lookup also validates the entry's credentials, so organizations with invalid keys are discarded and the integration continues ingesting from the remaining valid organizations. - When an entry provides both
datadogOrgNameanddatadogOrgPublicId, the integration uses those values as-is and skips the startup lookup, along with its credential validation. Make sure the keys for these entries are correct, since invalid credentials will only surface later during resync. - In multi-org mode, every ingested resource is enriched with two fields identifying its source organization:
__org_id(the public UUID) and__org_name(the human-readable name). Reference them in your mapping (for example, in the entityidentifier) to keep resources that share an ID across organizations from colliding in Port.
Configuration
Port integrations use a YAML mapping block to ingest data from the third-party api into Port.
The mapping makes use of the JQ JSON processor to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.
Default mapping configuration
This is the default mapping configuration for this integration:
Default mapping configuration (click to expand)
deleteDependentEntities: true
createMissingRelatedEntities: true
enableMergeEntity: true
resources:
- kind: monitor
selector:
query: "true"
port:
entity:
mappings:
identifier: .id | tostring
title: .name
blueprint: '"datadogMonitor"'
properties:
tags: .tags
monitorType: .type
overallState: .overall_state
thresholds: .thresholds
priority: .priority
createdBy: .creator.email
createdAt: .created
updatedAt: .modified
link: (\"https://app.datadoghq.com/monitors/\" + (.id | tostring))
relations:
owner_team_datadog: .tags | map(select(startswith("team:"))) | unique | map(split(":")[1])
service_datadog: .tags | map(select(startswith("service:"))) | unique | map(split(":")[1])
service:
combinator: '"and"'
rules:
- property: '"datadog_service_id"'
operator: '"in"'
value: .tags | map(select(startswith("service:"))) | unique | map(split(":")[1])
- kind: service
selector:
query: "true"
port:
entity:
mappings:
identifier: .attributes.schema.\"dd-service\"
title: .attributes.schema.\"dd-service\"
blueprint: '"datadogService"'
properties:
application: .attributes.schema.application
languages: .attributes.schema.languages
description: .attributes.schema.description
tags: .attributes.schema.tags
type: .attributes.schema.type
links: (\"https://app.datadoghq.com/services?selectedService=\" + (.attributes.schema.\"dd-service\"))
owners: '[.attributes.schema.contacts[]? | select(.type == "email") | .contact]'
relations:
owner_team_datadog: .team_it_doesnt_work_yet
- kind: slo
selector:
query: "true"
port:
entity:
mappings:
identifier: .id | tostring
title: .name
blueprint: '"datadogSlo"'
properties:
tags: .tags
sloType: .type
description: .description
warningThreshold: .warning_threshold
targetThreshold: .target_threshold
createdBy: .creator.email
createdAt: .created_at | todate
updatedAt: .modified_at | todate
link: (\"https://app.datadoghq.com/slo/manage?sp=\" + (\"%5B%7B%22p%22%3A%7B%22id%22%3A%22\" + (.id | tostring) + \"%22%7D%2C%22i%22%3A%22slo-panel%22%7D%5D\"))
relations:
monitors: .monitor_ids | map(tostring)
owner_team_datadog: .monitor_tags + .tags | map(select(startswith("team:"))) | unique | map(split(":")[1])
service_datadog: .monitor_tags + .tags | map(select(startswith("service:"))) | unique | map(split(":")[1])
service:
combinator: '"and"'
rules:
- property: '"datadog_service_id"'
operator: '"in"'
value: .monitor_tags + .tags | map(select(startswith("service:"))) | unique | map(split(":")[1])
- kind: host
selector:
query: '[.sources[] | . as $source | ["azure", "gcp", "gce", "aws"] | contains([$source])] | any(.)'
port:
entity:
mappings:
identifier: .id | tostring
title: .aws_name // .host_name
blueprint: '"datadogCloudResource"'
properties:
up: .up
host_name: .host_name
platform: .meta.platform
is_muted: .is_muted
machine: .meta.machine
description: .description
sources: .sources
cpu_cores: .meta.cpuCores
agent_version: .meta.agent_version
tags: .tags_by_source
- kind: host
selector:
query: "true"
port:
entity:
mappings:
identifier: .id | tostring
title: .aws_name // .host_name
blueprint: '"datadogHost"'
properties:
up: .up
host_name: .host_name
platform: .meta.platform
is_muted: .is_muted
machine: .meta.machine
description: .description
sources: .sources
cpu_cores: .meta.cpuCores
agent_version: .meta.agent_version
tags: .tags_by_source
- kind: user
selector:
query: "true"
port:
entity:
mappings:
identifier: .id | tostring
title: .attributes.name
blueprint: '"datadogUser"'
properties:
email: .attributes.email
handle: .attributes.handle
status: .attributes.status
disabled: .attributes.disabled
verified: .attributes.verified
createdAt: .attributes.created_at | todate
- kind: team
selector:
query: "true"
port:
entity:
mappings:
identifier: .id
title: .id
blueprint: '"datadogTeam"'
- kind: team
selector:
query: "true"
includeMembers: "true"
port:
entity:
mappings:
identifier: .id | tostring
title: .attributes.name
blueprint: '"datadogTeam"'
properties:
description: .attributes.description
handle: .attributes.handle
userCount: .attributes.user_count
summary: .attributes.summary
createdAt: .attributes.created_at | todate
relations:
members: if .__members then .__members[].id else [] end
- kind: role
selector:
query: "true"
port:
entity:
mappings:
identifier: .id | tostring
title: .attributes.name
blueprint: '"datadogRole"'
properties:
createdAt: .attributes.created_at | todate
modifiedAt: .attributes.modified_at | todate
custom: if .attributes.managed == true then false else true end
userCount: .attributes.user_count
Mapping & selectors per resource
Use the explorer below to view sample payloads and the resulting Port entities for each resource type. For additional resources and advanced configurations, see the examples page.
- kind: monitor
selector:
query: 'true'
port:
entity:
mappings:
identifier: .id | tostring
title: .name
blueprint: '"datadogMonitor"'
properties:
tags: .tags
monitorType: .type
overallState: .overall_state
thresholds: .thresholds
priority: .priority
createdBy: .creator.email
createdAt: .created
updatedAt: .modified
link: (\"https://app.datadoghq.com/monitors/\" + (.id | tostring))
relations:
owner_team_datadog: .tags | map(select(startswith("team:"))) | unique | map(split(":")[1])
service_datadog: .tags | map(select(startswith("service:"))) | unique | map(split(":")[1])
service:
combinator: '"and"'
rules:
- property: '"datadog_service_id"'
operator: '"in"'
value: .tags | map(select(startswith("service:"))) | unique | map(split(":")[1])
{
"id":15173866,
"org_id":1000147697,
"type":"query alert",
"name":"A change @webhook-PORT",
"message":"A change has happened",
"tags":[
"app:webserver"
],
"query":"change(avg(last_5m),last_1h):avg:datadog.agent.running{local} by {version,host} > 40",
"options":{
"thresholds":{
"critical":40.0,
"warning":30.0
},
"notify_audit":false,
"include_tags":true,
"new_group_delay":60,
"notify_no_data":false,
"timeout_h":0,
"silenced":{
}
},
"multi":true,
"created_at":1706707941000,
"created":"2024-01-31T13:32:21.270116+00:00",
"modified":"2024-02-02T16:31:40.516062+00:00",
"deleted": null,
"restricted_roles": [
"83659eba-5ce6-11f1-b7ce-da7ad0900002",
"dbd83320-396e-11ef-bf24-da7ad0900002"
],
"priority":5,
"overall_state_modified":"2024-03-08T20:52:46+00:00",
"overall_state":"No Data",
"creator":{
"name":"John Doe",
"email":"john.doe@gmail.com",
"handle":"john.doe@gmail.com",
"id":1001199545
},
"matching_downtimes":[
]
}
{
"identifier": "15173866",
"title": "A change @webhook-PORT",
"icon": "Datadog",
"blueprint": "datadogMonitor",
"team": [],
"properties": {
"tags": [
"app:webserver"
],
"overallState": "No Data",
"priority": "5",
"createdAt": "2024-01-31T13:32:21.270116+00:00",
"updatedAt": "2024-02-02T16:31:40.516062+00:00",
"createdBy": "john.doe@gmail.com",
"monitorType": "query alert"
},
"relations": {},
"createdAt": "2024-05-29T09:43:34.750Z",
"createdBy": "<port-client-id>",
"updatedAt": "2024-05-29T09:43:34.750Z",
"updatedBy": "<port-client-id>"
}
Port's Datadog integration syncs Service entities from service definitions in the Datadog Service Catalog API (via the GET /api/v2/services/definitions endpoint).
That is separate from APM services, which Datadog discovers automatically from APM tracing. The Service kind does not fetch them. The catalog entity kind fetches them only when its includeDiscovered selector is enabled.
Set up live events
- Hosted by Port
- Self-hosted
The Datadog integration keeps your catalog up to date in near real time through two complementary channels. Both are available for all installation methods.
The two channels carry different event types and are not interchangeable. Configure both for full coverage:
| Channel | Carries |
|---|---|
| 1. Monitor notifications | Monitor state transitions (for example OK → Alert → OK) and service dependency updates |
| 2. Audit trail forwarding | Configuration changes to monitors, SLOs, users, roles and teams, plus restriction policy changes |
The Datadog audit trail records user and API initiated actions, so a monitor changing state on its own does not appear in it. The overallState property on your monitor entities is therefore updated in real time only through channel 1; with channel 2 alone it refreshes on the next scheduled resync.
Live events base URL
For integrations installed using the Hosted by Port method, you can obtain the live events base URL from the Get an integration API. The response includes liveEventsUuid and liveEventsIngestHostname in the appSpec section.
Call the endpoint with your integration's identifier:
curl -X GET \
'https://api.port.io/v1/integration/<INTEGRATION_IDENTIFIER>' \
-H 'Authorization: Bearer <PORT_ACCESS_TOKEN>'
The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:
- EU (app.port.io) →
https://api.port.io - US (app.us.port.io) →
https://api.us.port.io
In the response, look for the following fields under spec.appSpec:
{
"spec": {
"appSpec": {
"liveEventsUuid": "abcdefghijk",
"liveEventsIngestHostname": "ingest.ocean.getport.io"
}
}
}
Combine them to build the live events base URL:
https://<liveEventsIngestHostname>/live-events/<liveEventsUuid>
For example, with the values above, the live events base URL is:
https://ingest.ocean.getport.io/live-events/abcdefghijk
This is the same URL configured for the integration.
1. Monitor notifications (automatic)
When the integration starts, it automatically registers a Datadog webhook and creates a monitor notification rule. Any monitor matching the configured scope sends state change events directly to Port - no manual setup required.
To register these objects automatically, the Datadog application key used by the integration must have the following permissions:
| Permission | Used for |
|---|---|
integrations_read | Read existing webhook configuration |
create_webhooks | Create the Port webhook |
manage_integrations | Update the Port webhook |
monitors_read | List existing notification rules |
monitor_config_policy_write | Create or update the monitor notification rule |
The following monitor alert types are supported: ci_pipelines_alert, ci_tests_alert, composite_monitor, error_tracking_alert, event_alert, event_v2_alert, log_alert, monitor_slo_alert, metric_slo_alert, outlier_monitor, process_alert, query_alert_monitor, rum_alert, service_check, synthetics_alert, trace_analytics_alert.
Use the monitorNotificationRuleScope configuration parameter to control which monitors trigger notifications (default: service:*, which captures all service monitors).
Example values:
service:*- all service monitors (default).service:my-service AND env:prod- monitors for a specific service and environment only.
Note that the default scope only matches monitors carrying a service tag. If your monitors are tagged differently, widen the scope accordingly, or those monitors will not send state change events to Port.
Manual registration (optional)
The webhook and the notification rule can also be created by a Datadog administrator rather than by the integration. The integration consumes the resulting events either way - automatic registration is a convenience, not a requirement.
You might prefer manual registration if you:
- manage Datadog resources as code, or through a change management process
- want explicit control over the naming, scope, and lifecycle of both objects
- want to reuse an existing webhook or notification rule instead of having a second one created
- cannot grant the application key the write permissions listed above, for example under a read-only credential policy
Automatic registration is the only part being replaced. You still need a live events base URL configured, and the application key still needs read access to monitors so the integration can fetch each monitor when an event arrives.
Registration steps (click to expand)
Step 1: Create the webhook in Datadog
- In Datadog, go to Integrations > Webhooks.
- Click New Webhook and fill in the following:
- Name: Any name you choose. Note it down - you will reference it in the next step.
- URL: Append
/integration/webhook/monitor-eventsto your live events base URL. - Payload: Enable Encode as JSON and enter the payload below exactly as shown.
- Custom headers: If you have set a
webhookSecret, add the following, replacing<your_webhook_secret>with its value. Skip this if you have not set a webhook secret.{"X-Port-Ocean-Webhook-Secret": "<your_webhook_secret>"}
- Save the webhook.
The payload template:
{
"id": "$ID",
"message": "$TEXT_ONLY_MSG",
"priority": "$PRIORITY",
"last_updated": "$LAST_UPDATED",
"event_type": "$EVENT_TYPE",
"event_url": "$LINK",
"service": "$HOSTNAME",
"service_id": "$SERVICE_ID",
"service_name": "$SERVICE_NAME",
"creator": "$USER",
"title": "$EVENT_TITLE",
"date": "$DATE",
"org_id": "$ORG_ID",
"org_name": "$ORG_NAME",
"alert_id": "$ALERT_ID",
"alert_metric": "$ALERT_METRIC",
"alert_status": "$ALERT_STATUS",
"alert_title": "$ALERT_TITLE",
"alert_type": "$ALERT_TYPE",
"tags": "$TAGS",
"body": "$EVENT_MSG"
}
Events missing event_type or alert_id are discarded, as are events missing org_name in multi-organization installations. Discards are silent, so an altered payload is difficult to diagnose.
Step 2: Create the monitor notification rule
- In Datadog, go to Monitors > Settings > Notification Rules.
- Create a new rule and add the webhook from step 1 as a recipient. Webhook recipients take the form
@webhook-<name>, where<name>is the webhook name from step 1. - Set the rule's scope to match the monitors you want to send state change events to Port.
- Save the rule.
Alternatively, add @webhook-<name> to the notification message of each individual monitor you want covered. A notification rule is usually preferable, since it applies to many monitors at once.
Step 3: Disable automatic registration
Set the skipWebhookCreation configuration parameter to true (integration.config.skipWebhookCreation for Helm installations), so the integration no longer attempts automatic registration on startup. It continues to receive and process live events normally.
2. Audit trail forwarding (manual setup required)
The integration processes Datadog audit trail events to reflect near-real-time changes to monitors, users, teams, SLOs, and roles in your catalog.
| Catalog entity | Datadog audit event |
|---|---|
| Monitor | Monitor |
| Monitor | Access Management (restriction policy) |
| SLO | SLO |
| SLO | Access Management (restriction policy) |
| User | Access Management |
| Role | Access Management |
| Team | Teams Management |
Datadog does not support managing audit trail forwarding destinations via its API. You must configure this destination manually in the Datadog UI, as described below.
To configure audit trail forwarding in Datadog:
- In Datadog, go to Organization Settings > Compliance > Audit Trail Settings.
- Under Forward Audit Events > Custom Destinations, click New Destination.
- Choose HTTP as the destination type and fill in the following:
- Destination URL: Append
/integration/webhook/audit-trailto your live events base URL. - Query filter: Enter the following query so that only events this integration handles are forwarded:
@asset.type:(monitor OR slo) OR @evt.name:("Access Management" OR "Teams Management")
- Authentication: Select Request Header and provide:
- Header name:
X-Port-Ocean-Webhook-Secret - Header value: The value of your
webhookSecretconfiguration. If you have not set a webhook secret, enter any random string - Datadog requires a non-empty value, and the integration will accept all requests regardless.
- Header name:
- Enable GZIP compression for payloads: Disable this option. It is enabled by default, but the integration expects uncompressed payloads.
- Destination URL: Append
- Save the destination.
BaseUrl & webhook configuration
To enable real-time updates of the data in your software catalog, you need to define the liveEvents.baseUrl parameter.
This parameter should be set to the URL of your Datadog integration instance, which needs to have the option to setup webhooks via HTTP requests/receive HTTP requests, so ensure the network is configured accordingly.
- If Datadog and the integration are in the same cluster/network: Use an internal URL (e.g., a Kubernetes service DNS name).
For Kubernetes deployments, create a service to expose the integration pod and use the service URL asliveEvents.baseUrl. If both the source system and integration are in the same cluster, an internal ClusterIP service is sufficient. - If Datadog is external to the integration's network: The integration must be exposed via an ingress, load balancer, or public URL that Datadog can reach.
If you're running high volumes of live events in a self-hosted deployment and want better reliability, event durability, or horizontal scalability, you can optionally set up Port's dedicated live events infrastructure. See live events at scale for details.
If liveEvents.baseUrl is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the scheduledResyncInterval parameter has to be set, or a manual resync will need to be triggered through Port's UI.
To test webhooks or live event delivery to your local environment, expose your local pod or service to the internet using ngrok (e.g. ngrok http http://localhost:8000)
The Datadog integration keeps your catalog up to date in near real time through two complementary channels. Both are available for all installation methods.
The two channels carry different event types and are not interchangeable. Configure both for full coverage:
| Channel | Carries |
|---|---|
| 1. Monitor notifications | Monitor state transitions (for example OK → Alert → OK) and service dependency updates |
| 2. Audit trail forwarding | Configuration changes to monitors, SLOs, users, roles and teams, plus restriction policy changes |
The Datadog audit trail records user and API initiated actions, so a monitor changing state on its own does not appear in it. The overallState property on your monitor entities is therefore updated in real time only through channel 1; with channel 2 alone it refreshes on the next scheduled resync.
1. Monitor notifications (automatic)
When the integration starts, it automatically registers a Datadog webhook and creates a monitor notification rule. Any monitor matching the configured scope sends state change events directly to Port - no manual setup required.
To register these objects automatically, the Datadog application key used by the integration must have the following permissions:
| Permission | Used for |
|---|---|
integrations_read | Read existing webhook configuration |
create_webhooks | Create the Port webhook |
manage_integrations | Update the Port webhook |
monitors_read | List existing notification rules |
monitor_config_policy_write | Create or update the monitor notification rule |
The following monitor alert types are supported: ci_pipelines_alert, ci_tests_alert, composite_monitor, error_tracking_alert, event_alert, event_v2_alert, log_alert, monitor_slo_alert, metric_slo_alert, outlier_monitor, process_alert, query_alert_monitor, rum_alert, service_check, synthetics_alert, trace_analytics_alert.
Use the monitorNotificationRuleScope configuration parameter to control which monitors trigger notifications (default: service:*, which captures all service monitors).
Example values:
service:*- all service monitors (default).service:my-service AND env:prod- monitors for a specific service and environment only.
Note that the default scope only matches monitors carrying a service tag. If your monitors are tagged differently, widen the scope accordingly, or those monitors will not send state change events to Port.
Manual registration (optional)
The webhook and the notification rule can also be created by a Datadog administrator rather than by the integration. The integration consumes the resulting events either way - automatic registration is a convenience, not a requirement.
You might prefer manual registration if you:
- manage Datadog resources as code, or through a change management process
- want explicit control over the naming, scope, and lifecycle of both objects
- want to reuse an existing webhook or notification rule instead of having a second one created
- cannot grant the application key the write permissions listed above, for example under a read-only credential policy
Automatic registration is the only part being replaced. You still need a live events base URL configured, and the application key still needs read access to monitors so the integration can fetch each monitor when an event arrives.
Registration steps (click to expand)
Step 1: Create the webhook in Datadog
- In Datadog, go to Integrations > Webhooks.
- Click New Webhook and fill in the following:
- Name: Any name you choose. Note it down - you will reference it in the next step.
- URL: Append
/integration/webhook/monitor-eventsto the base URL you configured in theliveEvents.baseUrlHelm parameter. - Payload: Enable Encode as JSON and enter the payload below exactly as shown.
- Custom headers: If you have set a
webhookSecret, add the following, replacing<your_webhook_secret>with its value. Skip this if you have not set a webhook secret.{"X-Port-Ocean-Webhook-Secret": "<your_webhook_secret>"}
- Save the webhook.
The payload template:
{
"id": "$ID",
"message": "$TEXT_ONLY_MSG",
"priority": "$PRIORITY",
"last_updated": "$LAST_UPDATED",
"event_type": "$EVENT_TYPE",
"event_url": "$LINK",
"service": "$HOSTNAME",
"service_id": "$SERVICE_ID",
"service_name": "$SERVICE_NAME",
"creator": "$USER",
"title": "$EVENT_TITLE",
"date": "$DATE",
"org_id": "$ORG_ID",
"org_name": "$ORG_NAME",
"alert_id": "$ALERT_ID",
"alert_metric": "$ALERT_METRIC",
"alert_status": "$ALERT_STATUS",
"alert_title": "$ALERT_TITLE",
"alert_type": "$ALERT_TYPE",
"tags": "$TAGS",
"body": "$EVENT_MSG"
}
Events missing event_type or alert_id are discarded, as are events missing org_name in multi-organization installations. Discards are silent, so an altered payload is difficult to diagnose.
Step 2: Create the monitor notification rule
- In Datadog, go to Monitors > Settings > Notification Rules.
- Create a new rule and add the webhook from step 1 as a recipient. Webhook recipients take the form
@webhook-<name>, where<name>is the webhook name from step 1. - Set the rule's scope to match the monitors you want to send state change events to Port.
- Save the rule.
Alternatively, add @webhook-<name> to the notification message of each individual monitor you want covered. A notification rule is usually preferable, since it applies to many monitors at once.
Step 3: Disable automatic registration
Set the skipWebhookCreation configuration parameter to true (integration.config.skipWebhookCreation for Helm installations), so the integration no longer attempts automatic registration on startup. It continues to receive and process live events normally.
2. Audit trail forwarding (manual setup required)
The integration processes Datadog audit trail events to reflect near-real-time changes to monitors, users, teams, SLOs, and roles in your catalog.
| Catalog entity | Datadog audit event |
|---|---|
| Monitor | Monitor |
| Monitor | Access Management (restriction policy) |
| SLO | SLO |
| SLO | Access Management (restriction policy) |
| User | Access Management |
| Role | Access Management |
| Team | Teams Management |
Datadog does not support managing audit trail forwarding destinations via its API. You must configure this destination manually in the Datadog UI, as described below.
To configure audit trail forwarding in Datadog:
- In Datadog, go to Organization Settings > Compliance > Audit Trail Settings.
- Under Forward Audit Events > Custom Destinations, click New Destination.
- Choose HTTP as the destination type and fill in the following:
- Destination URL: Append
/integration/webhook/audit-trailto the base URL you configured in theliveEvents.baseUrlHelm parameter. - Query filter: Enter the following query so that only events this integration handles are forwarded:
@asset.type:(monitor OR slo) OR @evt.name:("Access Management" OR "Teams Management")
- Authentication: Select Request Header and provide:
- Header name:
X-Port-Ocean-Webhook-Secret - Header value: The value of your
webhookSecretconfiguration. If you have not set a webhook secret, enter any random string - Datadog requires a non-empty value, and the integration will accept all requests regardless.
- Header name:
- Enable GZIP compression for payloads: Disable this option. It is enabled by default, but the integration expects uncompressed payloads.
- Destination URL: Append
- Save the destination.
Monitoring and sync status
To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.
Examples
To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your connectors page. Find the integration in the list of connectors and click on it to open the playground.
Examples of blueprints and the relevant integration configurations can be found on the datadog examples page
Relevant Guides
For relevant guides and examples, see the guides section.