Crate relay_conventions

Expand description

Relay’s interface to sentry-conventions.

This crate contains the sentry-conventions repository as a git submodule.

§Attributes

Attribute definitions in sentry-conventions are parsed at build time. For each attribute, this crate exposes:

A constant whose value is the attribute’s key in sentry-conventions. This constant has a deprecation tag if the attribute is marked as deprecated in sentry-conventions, leading to a compiler warning if it’s used anyway.
A record of the attribute’s relevant parameters (PII status, backfilling normalizing behavior). These records can be queried using the attribute_info function.

§Attribute normalization

Deprecated attributes can have their _status set to null, "backfill", or "normalize" in sentry-conventions. These values affect how Relay normalizes the attribute:

null: The attribute is left unchanged.
"backfill": The attribute’s value is copied to the replacement attribute, but an existing value for the replacement attribute is not overwritten. Thus, if the replacement attribute is already present, nothing happens.
"normalize": The attribute’s value is moved to the replacement attribute, but an existing value for the replacement attribute is not overwritten. Thus, if the replacement attribute is already present, the deprecated attribute is deleted.

This normalization step runs before other steps (user agent detection, category detection, …) that depend on specific attributes. Therefore, those other normalizations only need to check the values of non-deprecated attributes.

§FAQ

§I’ve changed something in `sentry-conventions`, how do I get Relay to pick it up?

Relay parses sentry-conventions at compile time, so any change requires a PR to Relay and needs to be deployed.

In Relay, Update the sentry-conventions submodule:

cd relay-conventions/sentry-conventions
git checkout main
git pull

Then open a PR with your change.

§Why is my deprecated attribute not being rewritten to the current name?

Make sure the attribute’s deprecation["_status"] field is set to either "backfill" or "normalize", depending on what you want to happen (see above). If this is set correctly and it’s still not working, verify the behaviour with an integration test and open an issue.

§After updating `sentry-conventions` I get a warning about a deprecated constant, what should I do?

This means that Relay is reading or writing an attribute that is deprecated in the new conventions version.

If the attribute has a replacement and is set to "backfill" or "normalize", you can just replace the constant with the current version and normalization takes care of the rest.
If the attribute has a replacement but no "backfill" or "normalize", consider changing that in sentry-conventions. Unless there is a good reason not to, you probably want the attribute to be rewritten.
Otherwise, we may have to decide what to do on a case-by-case basis.

§I want to reference an attribute in Relay but it’s not defined in `sentry-conventions`, what should I do?

Always define it in sentry-conventions before using it in Relay. This makes sure we have proper

Modules§

attributes: Attribute constant definitions.
interpolate: Functions for interpolating attribute keys with placeholders.
measurements: Measurement constant definitions.

Structs§

AttributeInfo: Information about an attribute, as defined in sentry-conventions.

Enums§

Pii: Whether an attribute should be PII-strippable/should be subject to datascrubbers
ReplacementName: The name of the replacement of a deprecated attribute.
WriteBehavior: Under which names an attribute should be saved.

Functions§

attribute_info: Returns information about an attribute, as defined in sentry-conventions.
attribute_info_with_fragment: Returns information about an attribute, as defined in sentry-conventions.
canonical: Returns the “canonical” version of an attribute. This means:
measurement_to_attribute: Returns the attribute replacing a measurement.
name_for_op_and_attributes