The Service Catalog and Ownership

The idea in one sentence

The Service Catalog answers a question none of metrics, logs, or traces can answer alone: who owns this service, what does it depend on, and where does its code actually live.

A definition, not a query

Metrics, logs, and traces are all things a service emits. A Service Catalog entry is different — it is a definition you declare about the service, adapted here for a billing-service:

apiVersion: v3
kind: service
metadata:
  name: billing-service
  owner: billing-team
spec:
  dependsOn:
    - service: checkout-service
datadog:
  codeLocations:
    - repositoryURL: https://github.com/org/billing-service.git
      paths:
        - "**"

metadata.owner is who to page. A metrics dashboard does not say who to notify at 3 a.m. when it fires. A log line does not say who wrote the service that produced it. A trace does not carry a Slack channel. metadata.owner is literally that missing field — a durable pointer to a team, independent of whether that team’s alert routing even happens to be wired correctly into a monitor today.

spec.dependsOn: an edge you declare, not one traffic infers

Compare spec.dependsOn with the Service Map from the APM module. The Service Map is auto-generated by observing live trace traffic between services — it shows what actually called what over the network, right now. spec.dependsOn is different: it is a manually declared edge in the Catalog, which means it can capture relationships that never generate a single span. billing-service might depend on a shared message queue that checkout-service publishes to asynchronously — no direct call, no trace connects them — or on a nightly batch job that reads a database table checkout-service owns. The Service Map shows you what talked to what; dependsOn lets you also declare what depends on what, including relationships that tracing was never going to see in the first place.

datadog.codeLocations: mapping a service to its source

repositoryURL and paths tie the abstract billing-service identity to an actual git repository, so tooling built on top of the Catalog — code security scanning, ownership-based review requirements — knows exactly where the code that produces this service’s telemetry lives, rather than someone maintaining that mapping in a spreadsheet or a wiki page that goes stale the moment it is written.

The piece the telemetry pipelines can’t provide

Metrics show resource usage. Logs show events. Traces show a request’s actual path through your services. None of the three can tell you who is responsible for a service, what it depends on beyond whatever happened to generate traffic today, or which repository to open to fix it. The Service Catalog is a small, deliberately-declared layer that exists specifically to answer those questions, and it stays useful even for a service that has no live traffic at all right now.

flowchart LR
  S["billing-service\n(Service Catalog entry)"] --> O["owner: billing-team"]
  S --> D["dependsOn: checkout-service"]
  S --> C["codeLocations: github.com/org/billing-service"]
  D -.not necessarily seen in.-> Tr[APM traces]

A Catalog entry, independent of live telemetry

🐶 The one-line takeaway

The Service Catalog is a service’s home page independent of any single telemetry signal — metadata.owner says who to page, spec.dependsOn lets you declare a dependency edge the Service Map’s live-traffic view might never see (a shared queue, a batch job), and datadog.codeLocations points straight at the source repository behind the service.

What question does metadata.owner in a Service Catalog entry answer that a trace or a metric cannot?

Which host the service is currently running on Who to page or notify about this specific service How many requests per second the service handles Which log index the service's logs are stored in

How does spec.dependsOn differ from the Service Map built in the APM module?

dependsOn is auto-generated from live trace traffic, exactly like the Service Map dependsOn is a manually declared edge that can capture dependencies that never appear in trace data, like a shared queue or batch job dependsOn replaces the Service Map and makes it redundant dependsOn only works for services with no traces at all

What does datadog.codeLocations map a service definition to?

Its Kubernetes namespace Its on-call schedule Its actual source repository and paths Its log processing pipeline

Which of the following can the Service Catalog answer that metrics, logs, and traces alone cannot?

The current error rate of a service Who owns a service and what it depends on structurally, independent of live telemetry The average latency of a service's endpoints The volume of logs ingested per day

Submit

Mark as complete