Hyphen

Datadog

Learn how to configure the Datadog integration in Hyphen to connect APM services and Kubernetes 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 and finding the inbound HTTP operation of each service.
timeseries_query Validating Kubernetes clusters, querying their metrics, and querying app request health.

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. Hyphen Agent uses the connection to query logs and HTTP request health 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.

Request Health

Hyphen reads HTTP request health from Datadog trace metrics: request count, 5xx responses, and p95 latency. To find the inbound HTTP operation, Hyphen looks for indexed server spans with HTTP attributes from the last 24 hours.

  • The service must have exactly one inbound HTTP operation. If it has none, or more than one, request health is unavailable.
  • Datadog stores tags in lowercase. Hyphen matches the service and env values in lowercase.
  • Agent marks request counts as incomplete if recent metrics are pending or some inbound requests lack an HTTP status code.

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 Application Health Checks 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.