dd-idp

# Datadog IDP Entity Graph Use Pup's read-only Unified Entity Graph (UEG) to discover software, ownership, work, and operational context. Its main payoff is connected context in one bounded request: a service plus its owners, systems, code, dependencies, and health signals through declared relationships. ## Choose the right surface - Default to `pup idp kinds` and `pup idp entities query` when the answer needs connected context across services, teams, systems, repositories, dependencies, work, operations, or security kinds. - Use `pup idp assist` when the user values a fast, curated single-service summary, metadata gaps, and suggested next actions over graph fidelity; use `owner` for convenient owner/on-call resolution. - Treat `find` as a simple paginated literal service-name lookup. Explicit `kind:` and `ref:` queries remain compatibility paths; use `entities query` for non-service kinds, another lookback, broader relation families, selected fields, counts, pagination, and traversal. Use `deps` as a convenient one-hour UEG runtime service-to-service dependency summary. - Use product commands such as `pup incidents`, `pup slos`, `pup monitors`, `pup logs`, `pup traces`, or `pup security` when the user needs deeper or current telemetry. - Use `idp entities facets` for observed field values and `idp entities aggregate` for grouped or filtered counts. Prefer these over paging an inventory just to count it. - Use `pup service-catalog` for the legacy typed service registry and `pup software-catalog` for Catalog entity/kind reads and writes. Do not use graph queries for mutations. ## Highest-value workflows - Build a service 360 in one request: owner/on-call, system and code placement, selected dependencies, and aggregate health. - Estimate blast radius by following declared or runtime service, datastore, queue, external-provider, and inferred-service relations relevant to the question. - Triage a team's portfolio from service health aggregates, then pivot to product APIs for detail. - Add deployment or infrastructure relations to ownership and dependencies for change context. - Inspect repository-linked APIs, code quality, secrets, and vulnerabilities without inventing service attribution. - Discover integration and custom kinds schema-first for tenant-specific work rather than relying on a fixed kind catalog. ## Schema-first workflow 1. Discover candidate kinds when the request is broad or the entity vocabulary is unfamiliar: ```bash pup --read-only idp kinds list pup --read-only idp kinds list --all --include-custom ``` 2. Describe each result kind before using unfamiliar fields or relations. Treat the live schema as authoritative: ```bash pup --read-only idp kinds describe service pup --read-only idp kinds describe integration.github.pull_request ``` 3. Query exactly one top-level result kind. Select only needed attributes with `--field`; expand only the relation family needed for the question with `--include`: ```bash pup --read-only idp entities query 'kind:service AND name:"<service-name>"' \ --field name,display_name,owner,service_health_status,active_incidents_count,alert_monitors_count,breached_slos_count \ --include owner_teams,systems,code_locations,upstream_services,downstream_services \ --relation-limit 3 \ --timeseries-interval 24h \ --limit 1 ``` This is the high-value default: identity, ownership, health, and declared service dependencies in one request. Add runtime, datastore, queue, deployment, or operational relations only when the question needs them; do not expand every service relation. 4. Inspect warnings, `page.truncated`, and every relationship's `count` and `truncated` state. For a bounded inventory, set an explicit result budget: ```bash pup --read-only idp entities query 'kind:service AND owner:"<team-handle>"' \ --field name,owner \ --limit 100 --max-results 500 ``` Check `page.stop_reason`; use `next_request.args` to continue if the budget was reached. Without `--max-results`, queries still fetch one page. 5. Follow returned refs instead of inventing joins: ```bash pup --read-only idp entities query 'ref:"ref:system:checkout"' \ --field name,display_name,owner \ --include services ``` 6. Synthesize only what the returned fields and declared relations establish. Label noisy matches as inferred and missing edges as unavailable. ## Correctness rules - Scope every query with one unquoted `kind:<kind>` or a concrete `ref:"ref:<kind>:<id>"`. - Keep the kind/ref outside alternatives: `kind:service AND (owner:payments OR team:payments)`. A top-level `OR` is invalid. - Never write `kind:"service"`; the quoted kind silently returns no results upstream and Pup rejects it. - `--field` selects attributes. `--include` expands relations. Discover both with `kinds describe` rather than guessing. - Use bare terms such as `kind:service AND catalog` with `--free-text-match partial`. The mode does not change field filters such as `name:*catalog*`. - Use lookbacks such as `1h`, `24h`, or `7d` for `--timeseries-interval`. See the DSL reference for absolute windows and property scopes. - Treat expanded relations as bounded samples. Increase `--relation-limit` or query the related kind directly when the full set matters. - Treat `null` or absent counts/booleans as unknown, never as zero or false. - Preserve source boundaries: UEG establishes graph facts; product APIs establish detailed operational facts. ## References - Read [UEG DSL](references/ueg-dsl.md) when constructing or paginating a query, choosing flags, or following relations. - Read [UEG footguns](references/footguns.md) when a query fails, unexpectedly returns zero, or touches timestamps, negation, high-cardinality relations, APIs, GitHub, Jira, scorecards, or security findings. - Read [IDP recipes](references/recipes.md) for one-step service context, dependency and change impact, team health, repository, PR, Jira, incident, SLO, API, and security workflows.