Restructure step metadata docs into reference page#1510
Open
Benanna2019 wants to merge 7 commits intomainfrom
Open
Restructure step metadata docs into reference page#1510Benanna2019 wants to merge 7 commits intomainfrom
Benanna2019 wants to merge 7 commits intomainfrom
Conversation
Restructures Andy's single metadata.mdx into a dedicated reference page following Diataxis. Strips narrative and how-to content, keeps the API surface clean: middleware setup, builder methods, scoping, custom kinds, built-in kinds, size limits, and limitations. DEV-276
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
djfarrelly
requested changes
Apr 1, 2026
Member
djfarrelly
left a comment
djfarrelly
left a comment
There was a problem hiding this comment.
key high level notes and some other questions for if some of this info could be useful elsewhere - generally I like the direction and the split here between this and the guide.
pages/docs/features/inngest-functions/steps-workflows/metadata.mdx
Outdated
Show resolved
Hide resolved
Comment on lines
+70
to
+72
| | *(omitted or `"default"`)* | `userland.default` | User Metadata | | ||
| | `"billing"` | `userland.billing` | User Metadata (billing) | | ||
| | `"analytics"` | `userland.analytics` | User Metadata (analytics) | |
Member
There was a problem hiding this comment.
question: Does the user ever see "userland" in the UI anywhere? I want to make sure that this is not just an internal implementation that we're exposing to our users and it's not visible in the UI.
Comment on lines
-250
to
-263
| ## Viewing metadata in the dashboard | ||
|
|
||
| Metadata is displayed in the **trace detail panel** when you select a span in the function run timeline. | ||
|
|
||
|  | ||
|
|
||
| Each metadata entry shows: | ||
|
|
||
| - **Kind label** -- "User Metadata" for the default kind, or "User Metadata (custom_kind)" for custom kinds | ||
| - **Scope** -- The level the metadata is attached to (run, step, or extended\_trace) | ||
| - **Updated at** -- Timestamp of when the metadata was last updated | ||
| - **Key-value pairs** -- Sorted alphabetically, with special formatting for byte values | ||
|
|
||
|  |
Member
There was a problem hiding this comment.
question: should this information be added to observability or traces guides in the learn tab? I wonder if this is useful information to describe how there is new trace metadata that can be helpful for debugging there? That may be a good place to surface this
|
|
||
|  | ||
|
|
||
| ## How it works |
Member
There was a problem hiding this comment.
question: Is this how it works helpful context anywhere? Maybe it is ok in a reference if someone really needs to understand what options are available and how it technically works.
- Rename from "Step metadata" to "Metadata" per team consensus - Remove "step" framing from descriptions (metadata attaches to runs) - Keep "userland" column pending Andy's confirmation on UI visibility - Note: URL path move to /docs/reference/ is a follow-up DEV-276
Lead with metadata as a step method alongside step.run, step.sleep, step.waitForEvent. This makes the memoization ID intuitive (every step tool takes one) and clarifies that step.metadata creates a step that attaches metadata, not metadata about a step. DEV-276
- Add concrete size calculation example ({ "status": "ok" } = ~10 bytes)
- Restore three-call custom kinds example with inline comments showing
default kind, custom billing kind, and custom analytics kind. Useful
as reference material for AI and developers.
DEV-276
…tadata Moves the reference page from the features section to the correct location alongside other step tool references (step-run, step-sleep, etc.). Adds a permanent redirect from the old path.
File has moved to pages/docs/reference/typescript/v4/functions/metadata.mdx
djfarrelly
approved these changes
Apr 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the single step metadata page from #1498 with a focused reference page following the Diataxis framework. Strips narrative and how-to content, keeping just the API surface:
metadataMiddleware()setupstep.metadata()andinngest.metadatamethod tablesThe companion how-to page is in a separate PR.
Relates to DEV-276.
Requested reviewers
@AndyInternet @djfarrelly