Hyphen
Log In

Datadog

Configure the Datadog integration in Hyphen to enable APM service mapping and Kubernetes cluster observability.

1. Sign into your Datadog account

Use the Datadog organization that receives your app and Kubernetes telemetry. Note its site domain, such as datadoghq.com or datadoghq.eu.

2. Create an access token

Create a Service Access Token for a Datadog service account:

  1. Open Organization Settings > Service Accounts and select the service account.
  2. Under Access Tokens, click + New Token.
  3. Give the token a name, choose an expiration, and select its scopes.
  4. Save and copy the token while it is visible.

A Personal Access Token can also authenticate the integration. Hyphen sends the token using Bearer authentication.

Grant the Datadog scopes needed for the connections you will use:

Scope Used for
logs_read_data Integration validation and querying app or Kubernetes logs.
apm_read Validating the services selected for APM connections.
timeseries_query Validating Kubernetes clusters and querying their metrics.

The token's owner must also have access to the telemetry Hyphen will query. Keep the token secure and replace it in Hyphen when it expires or is rotated.

3. Connect Datadog

In Hyphen's Integrations area, select Datadog and enter the site domain and access token. Hyphen validates access with a log query before saving the integration.

Use the site domain without a protocol or api. prefix. Hyphen supports these Datadog sites: datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, and us2.ddog-gov.com.

Configuration

Field Type Description
site string Datadog site domain. Defaults to datadoghq.com.
accessToken string (required) Access token supplied during setup.
secrets object Built during integration setup containing:
  accessToken string Stored token used to authenticate future requests.

Connections

Table of Contents

APM

APM connections map a Hyphen app to existing Datadog services so Hyphen Agent can query its logs for the selected environment.

Before You Connect

  • Send app traces and logs to the connected Datadog organization.
  • Ensure each selected service has indexed spans from the last 24 hours. Hyphen uses those spans to validate the service name.
  • Include the service tag on logs. For a shared service, include an env tag whose value matches the Hyphen project environment identifier, such as production.

Configuration

Field Type Description
mode string (required) sharedByEnvironmentAttribute or perEnvironment.
entityName string Exact Datadog service name for shared mode.
environmentAttribute string Must be env for shared mode.
environments object Required in per-environment mode. Maps every project environment identifier to an object containing its service's entityName.

Connection Input

Provide a JSON service mapping when connecting APM for the app. Use exact service names without wildcards or search expressions.

For one service shared across environments:

{
  "mode": "sharedByEnvironmentAttribute",
  "entityName": "checkout-api",
  "environmentAttribute": "env"
}

For separate services in a project with development and production environments:

{
  "mode": "perEnvironment",
  "environments": {
    "development": { "entityName": "checkout-api-development" },
    "production": { "entityName": "checkout-api-production" }
  }
}

The mapping must cover all project environments exactly. If service validation returns a not-found error, check the service name and confirm indexed spans have arrived within the last 24 hours.

See Log Analysis for using the connection with Hyphen Agent.

Kubernetes Observability

Kubernetes Observability connections let Hyphen Agent query Datadog metrics and logs for a registered cluster.

Before You Connect

  • Install and configure Datadog's Kubernetes monitoring, including Kubernetes State Core and log collection.
  • Ensure the connected organization receives kubernetes_state.node.count samples tagged with the cluster's kube_cluster_name.
  • Include kube_cluster_name, kube_namespace, and pod_name on workload telemetry. Container metrics also use kube_container_name.
  • Collect container CPU and memory usage, resource requests, and restart metrics so Agent can assess utilization.

Configuration

Field Type Description
clusterName string Cluster name stored after connection validation. Matches the emitted kube_cluster_name tag.

Connection Input

Provide the exact lowercase kube_cluster_name tag value. Hyphen checks for Kubernetes State Core node-count samples with that name in the last 24 hours. If none are available, the connection returns a not-found error; correct the name or wait for telemetry, then retry.

When observability discovery is enabled, Hyphen may create the connection automatically if Horizon detects exactly one Datadog cluster name and the organization has exactly one Datadog integration. Otherwise, connect it from the registered cluster's Settings tab.

For complete setup instructions, see Kubernetes Observability.