@sentry/conventions 0.19.0 → 0.20.0

package/README.md

@@ -23,5 +23,27 @@
 The package exports:
 
 - `attributes`: contains constants for all attribute names and their types, as defined in the Sentry semantic conventions
+- `attributes.ATTRIBUTE_METADATA`: provides metadata about attributes, such as their type, scrubbing definition, deprecation info, and lookup keys
 - `attributes.Attributes`: represents a bag of typed attributes
 - `op`: contains constants for span operations used in Sentry
+
+## Attribute Key Chains
+
+An attribute's value may be readable under several keys: its own, the names Sentry search exposes it as, and the deprecated attributes it replaces. `ATTRIBUTE_METADATA[key].keys` lists all of them, most preferred first:
+
+```ts
+import { ATTRIBUTE_METADATA, HTTP_METHOD } from '@sentry/conventions/attributes';
+
+ATTRIBUTE_METADATA[HTTP_METHOD].keys;
+// ['http.request.method', 'http.method', 'http.request_method', 'method']
+```
+
+The order within a chain is:
+
+1. the attribute heading the chain, followed by the names it is exposed as in Sentry search
+2. its non-deprecated aliases, each followed by their own search names
+3. the deprecated attributes it replaces, in alphabetical order, each followed by their own search names
+
+Deprecated attributes are only added to a chain if their status is `normalize` or `backfill`.
+If an attribute is deprecated with another status or status `null`, it's own `keys` array will not contain any
+replacing attribute. Therefore, there's **no guarantee** for a stable attribute in a key chain.