docs(incidents): list the entity types that support incidents - #18685

+1 on documenting this. I hit the same limitation independently on DataHub Core v1.5.0.6, while trying to raise an incident on an mlModel from an agent, and arrived at exactly the workaround this PR recommends: raise it on the dataset the model trained on, and name the model in the body.

Adding the other error message for searchability, since it differs from the one in the description. A raiseIncident mutation with an mlModel URN in resourceUrns returns:

java.lang.RuntimeException: Invalid format for aspect: incident
 Cause: ERROR :: /entities/0 :: "Provided urn urn:li:mlModel:(urn:li:dataPlatform:duckdb,nyc_fare_predictor,PROD)" is invalid:
        Entity type for urn urn:li:mlModel:(urn:li:dataPlatform:duckdb,nyc_fare_predictor,PROD) is not supported

This PR quotes is not a valid destination. Both wordings are in the wild, and neither names the supported set, so a reader who searches the first string will not find the second. Worth covering both in the docs page.

One note on why this matters beyond documentation, for the ML case specifically. The model is the thing that degraded, the thing an on-call engineer opens, and the thing whose health a team watches. Because it cannot carry an incident, the model page reads healthy while the model is measurably wrong, and the signal has to live one hop upstream on a dataset that is itself fine. Supporting ML entities as incident resources, even without full health roll-up, would close that gap.

Happy to test a patch against a local v1.5.0.6 instance if that is useful.

Confirmed, and thanks for the second string. I only ever hit the first one, so I had no way to know there were two.

They look like different checks. Yours comes back wrapped in Invalid format for aspect: incident, so that is the aspect validator refusing the write. Mine has no wrapper and reads like the destination check further out. Same result either way, nothing is written, but which message you get depends on which one you trip first. Pushed both to the docs now, normalised onto the same example URN, with a line saying they are the same failure so a search for either string lands here.

On the ML point, that is exactly the case I hit. I have an agent that does root cause on model degradation by walking lineage, and the one thing it cannot do is leave the finding on the model. It writes to the training dataset instead. So the dataset page ends up carrying a warning about something that is not wrong with the dataset, and the model page stays clean while the model is the thing that is broken. On call opens the model page.

I want to keep this PR as docs so it can land on its own. I will open a separate issue for supporting mlModel as an incident resource and tag you there. If a maintainer signals they would take it, that v1.5.0.6 test would be worth a lot, because the registry side looks small and the UI side probably is not.

Issue opened for the ML case: #18999. This PR stays docs only.

Correcting my earlier comment on this PR, because it was wrong and it should not
stand in a thread people will search.

I posted this as an mlModel rejection:

java.lang.RuntimeException: Invalid format for aspect: incident
 Cause: ERROR :: /entities/0 :: "Provided urn urn:li:mlModel:(...)" is invalid:
        Entity type for urn ... is not supported

I cannot reproduce it. On DataHub Core v1.5.0.6 a raiseIncident with an
mlModel URN in resourceUrns succeeds, and the incident persists against
the model. mlFeature too. What does reject is mlModelGroup,
mlFeatureTable and dataProcessInstance, and their message is a third wording
again: Entity type for urn: <urn> is not a valid destination for field path: /entities/*.

My best guess at what I actually hit is that I misattributed a failure whose
real cause was one of the other write-back bugs I was fixing at the time
(DATA_QUALITY is not a member of IncidentType; customType is required when
type is CUSTOM). Both fail the whole mutation regardless of the resource
URN.

Where that leaves the docs change in this PR: the supported list here comes from
the entity registry, and for mlModelGroup and mlFeatureTable it matches what
the instance does. For mlModel and mlFeature the write is accepted, so
"do not support incidents" is not quite the behaviour. The accurate statement is
that an incident on an mlModel is stored and cannot be read back, because
MLModel has no incidents field in the GraphQL schema
(Field 'incidents' in type 'MLModel' is undefined), while Dataset.incidents
exists. Might be worth a sentence, since a reader who tries it will get a
success and an incident URN.

Full sweep and raw output in #18999.

Separately, on the review note about the workaround being "one hop of lineage":
the reviewer is right to push back. In my own instance the model reaches the raw
dataset through a feature table and dbt models, not in one hop, and an instance
with no training lineage populated would not reach it at all. "A training dataset
linked to the model" is the safer phrasing.

Sorry for the noise. Better to correct it here than leave it for whoever searches
that string.

@AdrianMachado agreed on generating it. Two things before I push, and the first one is me correcting my own PR.

The table is wrong, and generating it from incidentsSummary would keep it wrong

I wrote this against a v1.5.0.6 instance where every ML write was rejected, and I wrote "the entity must carry the incidentsSummary aspect" as though that were the write gate. It is not. The write gate is the IncidentOn relationship in IncidentInfo.pdl. Derived from master just now:

Ten write destinations, seven summaries, five readable.

So on master, "Anything else is rejected and nothing is written" is false, and "mlModel ... do not support incidents" is false. Those writes are accepted and the caller gets an incident URN back. They just cannot be read. That is my error, it came from generalising one version's behaviour, and it should not ship regardless of what we decide about generation.

The error strings need redoing for the same reason. Of the two I quoted, the second is the wording Jonathan could not reproduce against an mlModel, and @Ahmedxsaad hit a third wording on v1.5.0.6 that is in neither. I would rather quote what is reproducible and say which version produced it than list strings from memory.

Which is the argument for generating more than one column. A table generated from incidentsSummary alone prints exactly the seven rows I hand wrote, and still tells a reader that mlModel is unsupported while their write returns an incident URN. Generating all three columns from the three sources describes what actually happens per layer, keeps the gaps visible instead of averaging them into a yes or no, and tightens itself as #18911 lands. Same reasoning as the CI guard in #19097, applied to the page a user reads first.

On where the generator lives

You pointed at generate_operation_capture_support_table in metadata-ingestion/scripts/docgen.py. That one builds its rows from the ingestion plugin scan and never reads the entity registry, so an incidents table there means running the connector doc scan to emit seven rows.

modeldocgen.py is the closer fit. It already takes --registry ../metadata-models/src/main/resources/entity-registry.yml, already builds entity_registry: Dict[str, EntityDefinition] with .aspects per entity, and already writes into docs/generated/metamodel. It runs as :metadata-ingestion:modelDocGen, which docs-website already depends on next to docGen. The summary column is nearly free there. The PDL and GraphQL columns need two small readers, which is the same parsing #19097 does on the test side.

Happy to put it in docgen.py instead if you would rather keep docs generation in one place. Your call, it is a small difference in the wiring and none in the output.

Two details, since they came up. docs/generated/ is gitignored, so the snippet is build output and not committed, same as the ingestion one. And the file is .md.snippet while mdPrettierCheck globs **/*.md, so the generated table is not prettier's problem either way.

The failing check

markdown_format_check is only cell padding in my hand written table. prettier wants the columns aligned. It disappears with the generated snippet, and I will clear it in the meantime so this is not sitting red.

Plan

1. Rewrite the section around the three layers and what each one controls, with the ML statement corrected and the error strings cut back to what is reproducible.
2. Three column table generated in modeldocgen.py, inlined with {{ inline ... }}.
3. Keep it accurate as the gaps close, rather than needing an edit per merge.

If you would rather this PR carried only the correction and the generated table came with PR1 of #18911, that is faster to review and I am happy either way. I have said in #18999 that I will take PR1, so the two would land together.

Pushed, four days later than it needed to be. I asked which file the generator should live in, said in the same breath that it was my call and the output was identical either way, and then waited on the answer anyway. Novel way to block yourself. Sorry for the delay.

The generator went into modeldocgen.py rather than docgen.py. It already loads the entity registry, and docs-website already depends on :metadata-ingestion:modelDocGen, so the ordering came for free and nothing new had to be wired. It is a --incident-support-output flag following the same shape as the existing --lineage-output.

Output is docs/generated/incidents/entity-support.md.snippet, gitignored like the ingestion one. The .md.snippet extension keeps it out of prettier's **/*.md glob, which also clears the markdown_format_check that was red on here.

Three columns, backend only: the IncidentOn write gate, the incidentsSummary aspect, and the extend type block in incident.graphql. I left the two frontend surfaces out on purpose. Parsing datahub-web-react from a metadata-model generator is the wrong boundary, and #19097 is a better home for keeping those from drifting. They are named in the prose with a pointer rather than dropped.

Re-derived against master before pushing: ten write destinations, seven summaries, five readable.

The correction to my own text is in. The page no longer says mlModel and mlFeature are rejected, because they are not: the write is accepted and returns an incident URN, and the problem is that nothing can read it back. The quoted rejection message now names the version it came from instead of being reproduced from memory, which is how it got wrong in the first place.

Two cubic threads were still open on here, and I had assumed both were stale. They were not. Both were right, and 493d62f fixes them.

The RaiseIncidentInput block on this page marked resourceUrn as String! and did not mention resourceUrns at all. On master resourceUrn is String, resourceUrns: [String!] exists, and each is required only when the other is absent. So the page told you a multi-resource incident was impossible to construct while the section immediately below it explained how the rules apply to resourceUrns. The block now matches the schema.

The second one is my error rather than an omission. I wrote that for mlModel and mlFeature "nothing reads the incident back". Incident implements Entity and the type is registered as a loadable type in GmsGraphQLEngine, so the URN the mutation returns resolves fine through the generic entity(urn: ...) query. The gap is on the asset side only: neither type can list its own incidents and neither renders them. I have corrected that in all three places it appeared, including the layer 3 description, which now says an entity without the extend type block cannot list incidents rather than that the incident cannot be fetched.

Worth noting what the shape of this was. Both findings sat under a resolved-looking pile of bot comments and both were marked outdated, because the lines they were attached to had moved. Outdated is not the same as addressed, and I treated it as if it were.

Nothing else changed. The generated table and the three-column scope are as described above, and CI was green before this push.

Hold for docs rebase (2026-08-20).

Land after Danish’s mlFeatureTable PR3 so the supported-types list is true. We now track seven gates (added MCP list_incidents fragments via #18341). schemaField stays API-only (no Incidents tab) in the docs.

Tracker: #19322 / Linear OBS-2085.

Unblocked (2026-08-21).

#19367 and #18911 are done. Please rebase so the supported-types docs match master (mlFeatureTable complete; schemaField API-only).

Tracker: #19322 / Linear OBS-2085.

Rebased onto master 11eb9ecf and pushed as 7d35e64e. Clean rebase, no conflicts.

Three things went in beyond the rebase.

The resolver gate is now derived. Column 3 claimed "Readable in GraphQL" and derived it from the SDL alone, which by your own gate 4 rule is not a claim the SDL can support. There are now two columns: incidents field in the SDL, and incidents resolver wired, the second parsed from the entitiesWithIncidents literal in GmsGraphQLEngine.java. The docs say why they are separate, which is that declaring the field without a resolver does not fail, it returns null, so it reads as an entity with no incidents rather than an unsupported one.

The generator had a false negative and I would have shipped it. The GraphQL type name was derived by capitalising the first letter, so mlModel became MlModel and matched nothing in either the SDL or the engine. Every ml entity would have printed No at gates 3 and 4 even though #19112, #19132 and #19367 closed them. It was invisible until mlModel actually became supported, because before that the wrong answer and the right answer were the same word. Fixed by handling the ML prefix next to the existing SchemaFieldEntity override. This is the same class of mistake that killed #19117, so it is worth saying out loud rather than folding into the rebase.

Current output, checked against master by hand:

Prose follows master. The ML paragraph is gone, since the write that looks like it worked and then goes nowhere is now service and aiAgent. Those two are a layer worse than the ML entities ever were: there is no Service or AIAgent type in the GraphQL schema at all, so there is nothing to hang the field on. schemaField is called out as API only, no Incidents tab, as you asked. The "any type absent from the table" line named mlFeatureTable, which is now supported, so that is corrected too.

One scope question rather than an assumption. Gate 7 is not derived. The MCP list_incidents fragments live in datahub-agent-context, outside the metadata model, and modeldocgen.py is a metadata-model generator, so reaching into that package is the same scope line I argued for keeping on the two frontend gates. It is named in the prose alongside them with a pointer to #19097 and #19322. Happy to derive it if you would rather the table carry all five parseable gates, but I did not want to widen the generator's reach without asking.

On verification: I cannot run :metadata-ingestion:lintFix here, no venv and the task assumes POSIX, so CI is the real check on formatting. The table output above came from running the generator functions directly against master. Prettier on docs/incidents/incidents.md is clean.

Follow-up on 002b1cab, plus a note on the red check.

The Gradle wiring was wrong in my last push. modelDocGen declares the PDL, the registry and the SDL as inputs, but the generator now also reads GmsGraphQLEngine.java for gate 4 and I did not declare it. So a change that touched only entitiesWithIncidents would leave the task up to date and the table stale, which is the exact drift this table is meant to stop. Declared now.

On ci (3.11, testIntegrationBatch1): it is tests/integration/nifi/test_nifi.py::test_nifi_ingest_cluster, a golden file mismatch. Not mine. The branch touches three files, none of them ingestion source: the docs page, modeldocgen.py, and the modelDocGen task in build.gradle. modeldocgen.py is a docs generator that nothing under src/ imports, and testIntegrationBatch1 is a different task.

That batch is unstable across the repo at the moment rather than on this branch. Looking at the last 25 runs of metadata-ingestion.yml, it is red on master and on at least four other people's branches in the same window, with a different golden file each time (oracle, neo4j, snowplow, git clone, nifi here). Nothing has touched the nifi source or its golden files in four days.

I cannot re-run it, I only have pull on this repo, so it needs someone else's push or a maintainer. Not urgent from my side since it is unrelated to the diff.

@AdrianMachado checking in on this one. With #19322 settled and schemaField staying API-only, the table this generates is already right, and there's nothing left for it to wait on.

I re-checked it against master today. The four things the generator reads (the IncidentOn list, the entities declaring incidentsSummary, the SDL incidents fields, and entitiesWithIncidents in GmsGraphQLEngine) are identical to the 21 Aug rebase, so the output hasn't moved. GitHub shows it mergeable, no conflicts.

The only thing holding it is the changes-requested review from 10 Aug, which asked for the table to be generated, and that's what it does now. Could you take another look when you get a chance?

@kyungsoo-datahub thanks for going through this. All nine are in, as two new commits on top so you can see just the changes. I also rebased a copy onto current master and it applied clean with the same tests passing.

Generator:

• The write gate now reads the block that names IncidentOn, whichever order its keys are in.
• A source that parses to nothing raises. You flagged two of these and the registry and SDL parsers had the same hole, so all four do it now.
• Derived type names get checked against the types defined across the SDL, and _INCIDENT_NO_GRAPHQL_TYPE covers service and aiAgent. That check runs both ways. If either gains a type (Service, AIAgent, ServiceEntity all count), leaves IncidentOn or loses incidentsSummary, the build fails and names the docs page. It reads every *.graphql now, so those are modelDocGen inputs too.
• Fixture tests for each parser, plus the smoke test you asked for against the real repo files.

Docs:

• Dropped the hand-picked absent types.
• Added the version caveat. On the v1.5.0.6 tag mlModel isn't on the IncidentOn list, so that's the example.
• The input block now has all 12 fields, copied from the current SDL.
• Also swapped the pointer from test(incidents): fail CI when incident entity support drifts across its three sources #19097 to test(incidents): fail CI when incident entity support drifts across its three sources #19629, since that one superseded it.

I broke each fix on purpose to see if a test noticed. One didn't: nothing failed if the table generator never called the guard. There's a test for that now, and all 12 breaks get caught.

test_modeldocgen.py passes, and ruff is clean. The real CLI writes the snippet from good sources and exits 1 with no snippet when one is broken. I only dry-ran the Gradle task locally, so CI is the real check on the modelDocGen wiring.