feat(sentry-instrument): add generated semantics lookup tree

skills/sentry-instrument/SKILL.md

@@ -95,6 +95,70 @@ Signals this skill wires up: error monitoring, tracing/performance, profiling (r
 tracing), logging, metrics, cron check-in code, session replay, user feedback, and
 AI/LLM monitoring.
 
+### Semantic conventions
+
+When naming custom span or log attributes, open **only** the matching domain reference
+below. Prefer these stable keys over invented names. Deprecated attributes are omitted.
+
+- [`angular`](references/semantics/angular.md)
+- [`app`](references/semantics/app.md)
+- [`art`](references/semantics/art.md)
+- [`aws`](references/semantics/aws.md)
+- [`browser`](references/semantics/browser.md)
+- [`cache`](references/semantics/cache.md)
+- [`client`](references/semantics/client.md)
+- [`cloud`](references/semantics/cloud.md)
+- [`cloudflare`](references/semantics/cloudflare.md)
+- [`code`](references/semantics/code.md)
+- [`culture`](references/semantics/culture.md)
+- [`db`](references/semantics/db.md)
+- [`device`](references/semantics/device.md)
+- [`error`](references/semantics/error.md)
+- [`event`](references/semantics/event.md)
+- [`exception`](references/semantics/exception.md)
+- [`faas`](references/semantics/faas.md)
+- [`file`](references/semantics/file.md)
+- [`flag`](references/semantics/flag.md)
+- [`gcp`](references/semantics/gcp.md)
+- [`gen_ai`](references/semantics/gen_ai.md)
+- [`general`](references/semantics/general.md)
+- [`graphql`](references/semantics/graphql.md)
+- [`grpc`](references/semantics/grpc.md)
+- [`http`](references/semantics/http.md)
+- [`jsonrpc`](references/semantics/jsonrpc.md)
+- [`jvm`](references/semantics/jvm.md)
+- [`koa`](references/semantics/koa.md)
+- [`logger`](references/semantics/logger.md)
+- [`mcp`](references/semantics/mcp.md)
+- [`mdc`](references/semantics/mdc.md)
+- [`messaging`](references/semantics/messaging.md)
+- [`middleware`](references/semantics/middleware.md)
+- [`navigation`](references/semantics/navigation.md)
+- [`nel`](references/semantics/nel.md)
+- [`network`](references/semantics/network.md)
+- [`os`](references/semantics/os.md)
+- [`otel`](references/semantics/otel.md)
+- [`params`](references/semantics/params.md)
+- [`process`](references/semantics/process.md)
+- [`react`](references/semantics/react.md)
+- [`remix`](references/semantics/remix.md)
+- [`resource`](references/semantics/resource.md)
+- [`rpc`](references/semantics/rpc.md)
+- [`score`](references/semantics/score.md)
+- [`sentry`](references/semantics/sentry.md)
+- [`server`](references/semantics/server.md)
+- [`service`](references/semantics/service.md)
+- [`session`](references/semantics/session.md)
+- [`state`](references/semantics/state.md)
+- [`thread`](references/semantics/thread.md)
+- [`timber`](references/semantics/timber.md)
+- [`trpc`](references/semantics/trpc.md)
+- [`ui`](references/semantics/ui.md)
+- [`url`](references/semantics/url.md)
+- [`user`](references/semantics/user.md)
+- [`user_agent`](references/semantics/user_agent.md)
+- [`vercel`](references/semantics/vercel.md)
+
 ## Step 4 — Verify it landed
 
 For a fresh install the spine already verified the first error.

skills/sentry-instrument/references/concepts/ai-monitoring.md

@@ -35,9 +35,9 @@ The span `op` is `gen_ai.{operation}` — `chat`, `embeddings`, `generate_conten
 **name** repeats the operation with its subject: `chat gpt-4o`,
 `invoke_agent Weather Agent`, `execute_tool get_weather`,
 `handoff from triage to billing`. Attributes accept primitives only; arrays/objects are
-JSON-stringified. The canonical attribute set is the
-[Sentry gen_ai conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/)
-— the SDK docs can lag, and attributes marked deprecated there should not be set.
+JSON-stringified. The canonical attribute set is
+[`semantics/gen_ai.md`](../semantics/gen_ai.md) — the SDK docs can lag, and
+deprecated attributes are omitted from that reference on purpose.
 
 ## Conversations
 

skills/sentry-instrument/references/concepts/tracing.md

@@ -42,8 +42,9 @@ A span also carries its profile, the bridge down to the function level.
   auto-instrumented), add custom spans for meaningful business operations, and keep span
   names **low-cardinality and templated** (`GET /users/:id`, not `/users/12345`) with
   searchable attributes rather than baking values into the name.
-  Follow Sentry’s semantic conventions (aligned with OpenTelemetry) for span and
-  attribute names so they match what the product expects.
+  Follow Sentry’s semantic conventions for span and attribute names. The core
+  [`SKILL.md`](../../SKILL.md#semantic-conventions) lists the domain references; open
+  only the one you need.
 
 ## Related
 

skills/sentry-instrument/references/semantics/angular.md

@@ -0,0 +1,8 @@
+# angular attributes
+
+Stable Sentry semantic convention attributes for `angular`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `angular.version` | `string` | The version of the Angular framework |

skills/sentry-instrument/references/semantics/app.md

@@ -0,0 +1,29 @@
+# app attributes
+
+Stable Sentry semantic convention attributes for `app`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `app.build` | `string` | Internal build identifier, as it appears on the platform. |
+| `app.identifier` | `string` | Version-independent application identifier, often a dotted bundle ID. |
+| `app.in_foreground` | `boolean` | Whether the application is currently in the foreground. |
+| `app.name` | `string` | Human readable application name, as it appears on the platform. |
+| `app.start_time` | `string` | Formatted UTC timestamp when the user started the application. |
+| `app.version` | `string` | Human readable application version, as it appears on the platform. |
+| `app.vitals.frames.delay.value` | `integer` | The sum of all delayed frame durations in seconds during the lifetime of the span. For more information see [frames delay](https://develop.sentry.dev/sdk/performance/frames-delay/). |
+| `app.vitals.frames.frozen.count` | `integer` | The number of frozen frames rendered during the lifetime of the span. |
+| `app.vitals.frames.frozen.rate` | `double` | The fraction of rendered frames that were frozen, calculated as `app.vitals.frames.frozen.count` divided by `app.vitals.frames.total.count`. This is computed by Relay. |
+| `app.vitals.frames.slow.count` | `integer` | The number of slow frames rendered during the lifetime of the span. |
+| `app.vitals.frames.slow.rate` | `double` | The fraction of rendered frames that were slow, calculated as `app.vitals.frames.slow.count` divided by `app.vitals.frames.total.count`. This is computed by Relay. |
+| `app.vitals.frames.total.count` | `integer` | The number of total frames rendered during the lifetime of the span. |
+| `app.vitals.stall.duration` | `double` | The combined duration of all stalls in milliseconds. Only applies to React Native. This is computed by Relay. |
+| `app.vitals.stall.percentage` | `double` | The fraction of transaction duration during which the app was stalled, between 0.0 and 1.0. For example, 0.8 represents 80%. Only applies to React Native. This is computed by Relay. |
+| `app.vitals.start.cold.value` | `double` | The duration of a cold app start in milliseconds |
+| `app.vitals.start.prewarmed` | `boolean` | Whether the app start was prewarmed. |
+| `app.vitals.start.reason` | `string` | The reason that triggered the app start. |
+| `app.vitals.start.screen` | `string` | The screen that is rendered when the app start is complete. This is the screen the user first sees and can interact with after launch. The absence of this attribute on the app start span indicates a background app start where no UI was rendered. |
+| `app.vitals.start.type` | `string` | The type of app start, for example `cold` or `warm` |
+| `app.vitals.start.warm.value` | `double` | The duration of a warm app start in milliseconds |
+| `app.vitals.ttfd.value` | `double` | The duration of time to full display in milliseconds |
+| `app.vitals.ttid.value` | `double` | The duration of time to initial display in milliseconds |

skills/sentry-instrument/references/semantics/art.md

@@ -0,0 +1,18 @@
+# art attributes
+
+Stable Sentry semantic convention attributes for `art`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `art.gc.blocking_count` | `integer` | Total number of blocking (stop-the-world) garbage collections performed by the Android Runtime |
+| `art.gc.blocking_time` | `double` | Total time spent in blocking (stop-the-world) garbage collections by the Android Runtime, in milliseconds |
+| `art.gc.pre_oome_count` | `integer` | Total number of garbage collections triggered as a last resort before an OutOfMemoryError by the Android Runtime |
+| `art.gc.total_count` | `integer` | Total number of garbage collections performed by the Android Runtime |
+| `art.gc.total_time` | `double` | Total time spent in garbage collection by the Android Runtime, in milliseconds |
+| `art.gc.waiting_time` | `double` | Total time threads spent waiting for garbage collection to complete in the Android Runtime, in milliseconds |
+| `art.memory.free` | `integer` | Free memory available to the process as reported by the Android Runtime, in bytes |
+| `art.memory.free_until_gc` | `integer` | Free memory available before a garbage collection would be triggered by the Android Runtime, in bytes |
+| `art.memory.free_until_oome` | `integer` | Free memory available before an OutOfMemoryError would be thrown by the Android Runtime, in bytes |
+| `art.memory.max` | `integer` | Maximum memory the process is allowed to use as reported by the Android Runtime, in bytes |
+| `art.memory.total` | `integer` | Total memory currently allocated to the process by the Android Runtime, in bytes |

skills/sentry-instrument/references/semantics/aws.md

@@ -0,0 +1,44 @@
+# aws attributes
+
+Stable Sentry semantic convention attributes for `aws`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `aws.cloudwatch.logs.log_group` | `string` | The name of the CloudWatch Logs log group |
+| `aws.cloudwatch.logs.log_stream` | `string` | The name of the CloudWatch Logs log stream |
+| `aws.cloudwatch.logs.url` | `string` | The URL to the CloudWatch Logs log group |
+| `aws.dynamodb.attribute_definitions` | `string[]` | The JSON-serialized value of each item in the `AttributeDefinitions` request field. |
+| `aws.dynamodb.consistent_read` | `boolean` | The value of the `ConsistentRead` request parameter. |
+| `aws.dynamodb.consumed_capacity` | `string[]` | The JSON-serialized value of each item in the `ConsumedCapacity` response field. |
+| `aws.dynamodb.count` | `integer` | The value of the `Count` response parameter. |
+| `aws.dynamodb.exclusive_start_table` | `string` | The value of the `ExclusiveStartTableName` request parameter. |
+| `aws.dynamodb.global_secondary_index_updates` | `string[]` | The JSON-serialized value of each item in the `GlobalSecondaryIndexUpdates` request field. |
+| `aws.dynamodb.global_secondary_indexes` | `string[]` | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field. |
+| `aws.dynamodb.index_name` | `string` | The value of the `IndexName` request parameter. |
+| `aws.dynamodb.item_collection_metrics` | `string` | The JSON-serialized value of the `ItemCollectionMetrics` response field. |
+| `aws.dynamodb.limit` | `integer` | The value of the `Limit` request parameter. |
+| `aws.dynamodb.local_secondary_indexes` | `string[]` | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. |
+| `aws.dynamodb.projection` | `string` | The value of the `ProjectionExpression` request parameter. |
+| `aws.dynamodb.provisioned_read_capacity` | `double` | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. |
+| `aws.dynamodb.provisioned_write_capacity` | `double` | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. |
+| `aws.dynamodb.scan_forward` | `boolean` | The value of the `ScanIndexForward` request parameter. |
+| `aws.dynamodb.scanned_count` | `integer` | The value of the `ScannedCount` response parameter. |
+| `aws.dynamodb.segment` | `integer` | The value of the `Segment` request parameter. |
+| `aws.dynamodb.select` | `string` | The value of the `Select` request parameter. |
+| `aws.dynamodb.table_count` | `integer` | The number of items in the `TableNames` response parameter. |
+| `aws.dynamodb.table_names` | `string[]` | The keys in the `RequestItems` object field. |
+| `aws.dynamodb.total_segments` | `integer` | The value of the `TotalSegments` request parameter. |
+| `aws.extended_request_id` | `string` | The AWS extended request ID as returned in the response headers. |
+| `aws.kinesis.stream_name` | `string` | The name of the AWS Kinesis stream the request refers to. |
+| `aws.lambda.execution_duration_in_millis` | `double` | The execution duration of the Lambda function invocation in milliseconds |
+| `aws.lambda.invoked_arn` | `string` | The full ARN of the Lambda function that was invoked |
+| `aws.lambda.remaining_time_in_millis` | `double` | The remaining time in milliseconds before the Lambda function times out |
+| `aws.log.group.names` | `string[]` | The name(s) of the AWS log group(s) an application is writing to. |
+| `aws.log.stream.names` | `string[]` | The name(s) of the AWS log stream(s) an application is writing to. |
+| `aws.request_id` | `string` | The AWS request ID as returned in the response headers. |
+| `aws.s3.bucket` | `string` | The S3 bucket name the request refers to. |
+| `aws.secretsmanager.secret.arn` | `string` | The ARN of the Secret stored in Secrets Manager. |
+| `aws.sns.topic.arn` | `string` | The ARN of the AWS SNS Topic. An Amazon SNS topic is a logical access point that acts as a communication channel. |
+| `aws.step_functions.activity.arn` | `string` | The ARN of the AWS Step Functions Activity. |
+| `aws.step_functions.state_machine.arn` | `string` | The ARN of the AWS Step Functions State Machine. |

skills/sentry-instrument/references/semantics/browser.md

@@ -0,0 +1,35 @@
+# browser attributes
+
+Stable Sentry semantic convention attributes for `browser`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `browser.bfcache.frame` | `string` | Which frame in the page's frame tree a back/forward cache not-restored reason originated from: the top document or a child frame. |
+| `browser.bfcache.not_restored_reason_count` | `integer` | The number of reported reasons a page was not restored from the back/forward cache on a back/forward navigation. 0 when the browser reported no reasons (e.g. non-Chromium browsers). |
+| `browser.bfcache.outcome` | `string` | Whether a back/forward navigation was restored from the browser's back/forward cache (bfcache). 'hit' means the page was restored; 'miss' means it was reloaded. |
+| `browser.bfcache.reason` | `string` | A browser-reported reason a page was not restored from the back/forward cache on a back/forward navigation, taken from the notRestoredReasons API. Reported per reason (a single miss can have several). Currently Chromium-only. |
+| `browser.name` | `string` | The name of the browser. |
+| `browser.performance.navigation.activation_start` | `double` | The time between initiating a navigation to a page and the browser activating the page |
+| `browser.performance.time_origin` | `double` | The browser's performance.timeOrigin timestamp representing the time when the pageload was initiated |
+| `browser.report.type` | `string` | A browser report sent via reporting API.. |
+| `browser.script.invoker` | `string` | How a script was called in the browser. |
+| `browser.script.invoker_type` | `string` | Browser script entry point type. |
+| `browser.script.source_char_position` | `integer` | A number representing the script character position of the script. |
+| `browser.version` | `string` | The version of the browser. |
+| `browser.web_vital.cls.report_event` | `string` | The event that caused the SDK to report CLS (pagehide or navigation) |
+| `browser.web_vital.cls.source.<key>` | `string` | The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N |
+| `browser.web_vital.cls.value` | `double` | The value of the recorded Cumulative Layout Shift (CLS) web vital |
+| `browser.web_vital.fcp.value` | `double` | The time it takes for the browser to render the first piece of meaningful content on the screen |
+| `browser.web_vital.fp.value` | `double` | The time in milliseconds it takes for the browser to render the first pixel on the screen |
+| `browser.web_vital.inp.value` | `double` | The value of the recorded Interaction to Next Paint (INP) web vital |
+| `browser.web_vital.lcp.element` | `string` | The HTML element selector or component name for which LCP was reported |
+| `browser.web_vital.lcp.id` | `string` | The id of the dom element responsible for the largest contentful paint |
+| `browser.web_vital.lcp.load_time` | `integer` | The time it took for the LCP element to be loaded |
+| `browser.web_vital.lcp.render_time` | `integer` | The time it took for the LCP element to be rendered |
+| `browser.web_vital.lcp.report_event` | `string` | The event that caused the SDK to report LCP (pagehide or navigation) |
+| `browser.web_vital.lcp.size` | `integer` | The size of the largest contentful paint element |
+| `browser.web_vital.lcp.url` | `string` | The url of the dom element responsible for the largest contentful paint |
+| `browser.web_vital.lcp.value` | `double` | The value of the recorded Largest Contentful Paint (LCP) web vital |
+| `browser.web_vital.ttfb.request_time` | `double` | The time it takes for the server to process the initial request and send the first byte of a response to the user's browser |
+| `browser.web_vital.ttfb.value` | `double` | The value of the recorded Time To First Byte (TTFB) web vital in Milliseconds |

skills/sentry-instrument/references/semantics/cache.md

@@ -0,0 +1,13 @@
+# cache attributes
+
+Stable Sentry semantic convention attributes for `cache`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `cache.hit` | `boolean` | If the cache was hit during this span. |
+| `cache.item_size` | `integer` | The size of the requested item in the cache. In bytes. |
+| `cache.key` | `string[]` | The key of the cache accessed. |
+| `cache.operation` | `string` | The operation being performed on the cache. |
+| `cache.ttl` | `integer` | The ttl of the cache in seconds |
+| `cache.write` | `boolean` | If the cache operation resulted in a write to the cache. |

skills/sentry-instrument/references/semantics/client.md

@@ -0,0 +1,9 @@
+# client attributes
+
+Stable Sentry semantic convention attributes for `client`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `client.address` | `string` | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. |
+| `client.port` | `integer` | Client port number. |

skills/sentry-instrument/references/semantics/cloud.md

@@ -0,0 +1,13 @@
+# cloud attributes
+
+Stable Sentry semantic convention attributes for `cloud`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `cloud.account.id` | `string` | The cloud account ID the resource is assigned to |
+| `cloud.availability_zone` | `string` | Cloud regions often have multiple, isolated locations known as zones to increase availability |
+| `cloud.platform` | `string` | The cloud platform in use |
+| `cloud.provider` | `string` | Name of the cloud provider |
+| `cloud.region` | `string` | The geographical region the resource is running |
+| `cloud.resource_id` | `string` | Cloud provider-specific native identifier of the monitored cloud resource |