Connect Prometheus or Datadog

Before you connect#

Impact Gate reads your existing observability data and matches it to APIs discovered in your selected repositories. Continue using Prometheus for metrics and Datadog for full traces, dashboards, and alerts. Impact Gate adds runtime evidence to API Flows, PR Impact, and Retirement Radar.

1. 1

   Index the API providers

   Connect GitHub and index repositories containing supported OpenAPI contracts. Confirm that the provider service and API paths appear in APIs.

2. 2

   Instrument every provider you want to observe

   Use your existing Prometheus client/exporter or Datadog APM library. Each observation must identify the provider service, HTTP method, and a stable route template such as /orders/{id}. Full URLs or paths containing individual customer IDs will not be guessed into API templates.

3. 3

   Prepare read credentials and access

   A workspace owner or admin with a verified identity can create the connection in Settings. Prometheus must be reachable from the Impact Gate deployment. Datadog requires an API key and an application key with the apm_read permission.

Connect Prometheus#

1. 1

   Check the metric in Prometheus

   Find a cumulative HTTP request counter with labels for provider service, HTTP method, and route template. Common names include http_requests_total or a request duration histogram's _count series. Adapt the query and label names to your application's instrumentation.

2. 2

   Open the connection form

   In Settings, choose Connect Prometheus. Enter the HTTPS query-server URL and select its authentication method. Enter a bearer token or username/password if required. The form starts with source access; it does not ask you to type every service name.

3. 3

   Adjust the defaults when needed

   The defaults use http_requests_total with service, method, and route labels over 24 hours. Windows can be configured up to 720 hours. Use at least 720 hours (30 days) for Retirement Radar to confirm an explicit zero-call counter. Open Advanced settings if your exporter uses another counter or labels. Keep {{window}} inside increase(). The query must return an instant vector of request counts rather than a rate per second.

4. 4

   Find and match services

   Choose Find and match services. Impact Gate reads service names from the source and compares them with indexed package names, repository names, deployment name variants, and API routes. Clear matches are preselected and grouped under matches ready to connect. Discovery does not save credentials or create a connection.

5. 5

   Review exceptions and connect

   Choose the correct indexed service from a dropdown for uncertain matches. Use all suggested matches applies the available suggestions in one action after your review. Leave services outside this workspace unselected. Choose Connect to validate and save the selected mappings, then open APIs. Manual mapping supports inactive services, additional aliases, and Fill with repository names without requiring discovery.

sum by (service, method, route) (increase(http_requests_total{route!=""}[{{window}}]))

http_requests_total{service="catalog-api-prod",method="GET",route="/orders/{id}"} 1234

For caller relationships, record a low-cardinality caller_service label when you have a trustworthy caller identity. Include it in sum by (service, method, route, caller_service) and set the optional Caller service label. Map the caller's service name too if you want a dependency edge to an indexed consumer.

Connect Datadog APM#

1. 1

   Confirm request spans exist

   Use Datadog's existing APM instrumentation for each API provider. In Trace Explorer, check that the selected environment has indexed server request spans, with the correct service and a route resource such as GET /orders/{id}. Configure retention in Datadog when the traffic you need is not indexed.

2. 2

   Create read credentials

   Create a Datadog API key and a scoped application key for an identity that can read APM (apm_read). In Settings, choose Connect Datadog, select your account's Datadog site, and enter both keys.

3. 3

   Select the spans and route fields

   The defaults use env:production, service, and resource_name. Open Advanced settings to use the same environment/provider filter as Trace Explorer and restrict it to server request spans. If your account uses separate route fields, choose @http.route and @http.method; custom attributes must be configured as searchable APM facets.

4. 4

   Discover, review, and connect

   Choose Find and match services to discover actual source names and preselect clear matches. Review the exceptions using dropdowns; use Use all suggested matches to apply the proposed matches together. Choose Connect to save. If a configured caller facet supplies consumer names, those names are discovered too. Saved imports are restricted to the selected source services within your configured query.

5. 5

   Inspect full traces in Datadog

   Use Open source from the connection card to open Datadog APM. Reuse the configured search query and observation window to investigate individual traces, errors, and latency there. Impact Gate imports aggregate evidence and does not copy raw spans or request payloads.

Read endpoint coverage#

Every indexed endpoint remains in the inventory, including endpoints with missing observations. In an endpoint's Overview, the Runtime observation section shows the source, request/span count, observation window, and whether caller identity is available. A query evaluation timestamp is not the last request timestamp, so Last observed can remain unavailable even when traffic counts are present. Retirement Radar highlights only connected, complete Prometheus counter results that explicitly report zero across at least 30 days; other candidates remain visible with their coverage and review state.

Use runtime evidence to investigate consumers#

Runtime data adds observed service and route activity to the static caller evidence from indexed repositories. A positive route observation shows that the mapped provider service received matching traffic during the configured window. It does not, by itself, identify which repository or source line made the request.

1. 1

   Verify the route match

   Compare the provider service mapping, HTTP method, and stable route template. /orders/123 is not guessed into /orders/{id}; emit a template from instrumentation or configure the source field correctly.

2. 2

   Check caller identity

   For Prometheus, aggregate a trustworthy low-cardinality caller_service label and set Caller service label. For Datadog, use a searchable caller facet. Map the caller value to an indexed consumer service before treating it as a dependency edge.

3. 3

   Compare static evidence

   Open the consumer source reference at its recorded commit and compare it with the observation window. Runtime route activity can confirm service-level use while leaving the exact call site unknown.

4. 4

   Record the coverage boundary

   Keep missing labels, sampled spans, group limits, stale imports, external clients, and unindexed repositories visible in the PR or deprecation review.

Refresh, edit, and disconnect#

• Each connection is imported automatically on a regular schedule; a busy queue can delay a refresh. Use Sync now in Settings to request an immediate import.
• Edit connection retains your saved mappings. Choose Find services again to discover new names. Changes to the source settings require discovery again, or manual mappings. For Prometheus choose Keep saved credentials; for Datadog leave both keys blank to retain them. Changing the origin/site requires fresh credentials. Choose No authentication only for a Prometheus source that permits unauthenticated reads.
• A failed import is shown as Sync error. Current endpoint coverage becomes unknown until a successful import. Observations that have gone stale are also excluded from current coverage.
• Disconnect removes the saved encrypted credentials and imported evidence for that source. Repositories and static evidence remain available. Disconnect does not modify your Prometheus or Datadog account; revoke an obsolete key in that provider as well.
• When both sources observe an endpoint, the inventory prefers Prometheus counter increases for volume and can use Datadog for caller evidence. Counts from the two sources are not added together.

Connect Kubernetes deployment identity#

Impact Gate links a GitHub repository to a running workload through build provenance or an explicit reviewed association. Repository, Deployment, Service, Prometheus, and Datadog names can all differ; name similarity alone never confirms identity.

1. 1

   Create namespace-scoped read access

   Use a dedicated service account and a RoleBinding only in namespaces you want to inventory. The connector reads Deployment, StatefulSet, DaemonSet, ReplicaSet, Pod owner/image status, and Service metadata. It does not read Secrets, logs, or execute in containers.

2. 2

   Connect the cluster in Settings

   Choose Connect cluster in the deployment identity panel. Enter an HTTPS API server origin, an environment, up to ten namespaces, and the read-only bearer token. Private API origins must be reachable from the backend and listed exactly in the operator's RUNTIME_ALLOWED_ORIGINS setting.

3. 3

   Provide build provenance or review a link

   Add the GitHub repository ID, full source commit SHA, and immutable sha256 image digest for a build, or choose Associate repository on a workload. The exact digest join reflects the submitted record; Impact Gate does not verify operator-submitted provenance against signed CI.

4. 4

   Review telemetry names separately

   Continue to map Prometheus and Datadog service names to indexed API services in each source connection. Kubernetes Service names and telemetry service names are not automatically treated as equivalent.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: impact-gate-inventory
  namespace: payments
rules:
  - apiGroups: [apps]
    resources: [deployments, statefulsets, daemonsets, replicasets]
    verbs: [get, list]
  - apiGroups: [""]
    resources: [pods, services]
    verbs: [get, list]

Resolve connection and coverage problems#