Adopt `opentelemetry-semantic-conventions` for OTel attribute names by ChihweiLHBird · Pull Request #3510 · spinframework/spin

ChihweiLHBird · 2026-05-14T16:26:44Z

Description

Adopt opentelemetry-semantic-conventions 0.28 for stable runtime span attribute names on outbound HTTP (factor-outbound-http) and the HTTP trigger (trigger-http), replacing string-literal field keys with crate constants where available.

Bump workspace tracing from 0.1.41 to 0.1.44 so #[instrument(fields(...))] accepts braced semconv constants (older tracing-attributes only parsed dotted field names there).

otel.kind, otel.name, and incubating http.response.body.size stay literals (with a short comment on body size). Spin-specific attributes (e.g. error.blame) are unchanged.

lann · 2026-05-14T16:35:54Z

FYI: https://docs.rs/tracing/latest/tracing/index.html#recording-fields:~:text=Constant%20expressions%20can,the%20constant%E2%80%99s%20name.

Constant expressions can also be used as field names. Constants must be enclosed in curly braces ({}) to indicate that the value of the constant is to be used as the field name, rather than the constant’s name.

ChihweiLHBird · 2026-05-14T16:51:25Z

FYI: https://docs.rs/tracing/latest/tracing/index.html#recording-fields:~:text=Constant%20expressions%20can,the%20constant%E2%80%99s%20name.

Constant expressions can also be used as field names. Constants must be enclosed in curly braces ({}) to indicate that the value of the constant is to be used as the field name, rather than the constant’s name.

Thanks! Let me try that. Do we want to include migrations for them in this PR as well?

Signed-off-by: Zhiwei Liang <zhiwei.liang@zliang.me>

lann · 2026-05-14T17:20:59Z

Do we want to include migrations for them in this PR as well?

Up to you.

ChihweiLHBird · 2026-05-14T19:37:25Z

Note that there are other experimental or deprecated semantic conventions that I left as string literals and didn't migrate to the constants in this PR. And it should be ready for review now. Let me know if anything else is needed.

lann · 2026-05-14T20:00:13Z

I probably should have started with this: looking at the diff now I'm not sure this is a net improvement. Avoiding typos is good, but there is also a downside here in that the constants make it harder to see the actual field names. That wouldn't be so bad if they were simply UPPERCASED versions of the field names but they also flatten periods into underscores... 🤔

ChihweiLHBird · 2026-05-14T20:22:14Z

@lann thanks for the thought! That's totally fair and I actually had a similar concern about it because this introduces another dependency.

The upside is the omitted key is still the dotted conventions and benefits of safer compile-time typo checks.
I personally feel it's easy to view the value of the constants too.

Another benefit is that the opentelemetry-semantic-conventions crate also makes us aware of the status of each semantic contention, like whether it's deprecated or experimental; so, we can avoid adding a deprecated key when building some new stuff.

I am okay if the team decide to not accept this, and feel free to close the PR in that case.

ChihweiLHBird · 2026-05-15T03:12:26Z

Another benefit is that the opentelemetry-semantic-conventions crate also makes us aware of the status of each semantic contention, like whether it's deprecated or experimental; so, we can avoid adding a deprecated key when building some new stuff.

An example of this is db.system, which is still widely used in spin but is actually deprecated. And it's marked as deprecated in the crate so triggers warnings in compile time, is used without #![allow(deprecated)].

calebschoepp

Did you make sure you found all possible attributes to replace?

Overall the advantages of getting warnings when things are deprecated seems worth it.

calebschoepp · 2026-05-15T14:53:11Z

@@ -1,5 +1,8 @@
 use anyhow::Result;
 use http::Response;
+use opentelemetry_semantic_conventions::attribute::{


Maybe we could just import all of opentelemetry_semantic_conventions::attribute with an alias of otel_attribute or something like that.

Good idea! Let me try that

Getting an alias to work in a macro is more complex than I thought. It would require use ::opentelemetry_semantic_conventions::attribute as otel_attribute; in the macro block and also in the modules where the macro is used. Can I leave this as is?

Using this pattern for all others seem to be fine and I pushed it here: 0b5917b

calebschoepp · 2026-05-15T14:54:36Z

@@ -397,12 +404,12 @@ impl p2::WasiHttpHooks for InstanceHttpHooks {
        skip_all,
        fields(
            otel.kind = "client",


Is this one not a convention?

Unfortunately, otel.kind is not an official convention and ~~is a spin specific thing...~~
You can see all otel.* keys in the conventions on this page and it doesn't contain otel.kind.

~~I would say another benefit of using the official convention crate is we can realize things like this earlier~~

otel.* is from tracing-opentelemetry: https://docs.rs/tracing-opentelemetry/latest/tracing_opentelemetry/#special-fields

@lann Thanks! Nice to know it

If we're switching to constants for standard keys it would probably be wise for us to create constants for these too, e.g. OTEL_KIND, OTEL_NAME. (tracing-opentelemetry doesn't seem to define them)

Scope creepily: I wouldn't be sad to have macros for these. We use otel.name and otel.kind quite a bit so e.g.:

#[instrument( otel_kind!("client"), // Lots of this pattern in crates/factor-outbound-redis/src/host.rs otel_name!("GET {key}"), )]

expanding to

#[instrument( {$crate::something_goes_here::OTEL_KIND} = "client", // Lots of this pattern in crates/factor-outbound-redis/src/host.rs {$crate::something_goes_here::OTEL_NAME} = format!("GET {path}"), )]

Note: if you haven't seen it, $crate is a magic macro variable: https://doc.rust-lang.org/reference/macros-by-example.html#r-macro.decl.meta.dollar-crate

Scope creepily: I wouldn't be sad to have macros for the otel.* fields. We use otel.name and otel.kind quite a bit

This looks like something for tracing-opentelemetry to add.

ChihweiLHBird · 2026-05-15T15:10:03Z

@calebschoepp thanks for the review!

Did you make sure you found all possible attributes to replace?

There are some experimental keys and some deprecated key I didn't replace with constants. The experimental keys require an additional feature of the crate, and the deprecate keys requir #![allow(deprecated)] in lib.rs. I can add them if you think that's fine. Personally I lean to leave it as is OR only add experimental feature. We can migrate the deprecated keys in the future then replace them with constants; so, we won't have to declare allowing any deprecated item in lib.rs

lann · 2026-05-15T15:42:12Z

I was on the fence so @calebschoepp can be the tie-breaker; I delegate my review to him. 🙂

Signed-off-by: Zhiwei Liang <zhiwei.liang@zliang.me>

Updated the usage of OpenTelemetry semantic conventions in the outbound HTTP crate to utilize the new aliasing for attribute names. Signed-off-by: Zhiwei Liang <zhiwei.liang@zliang.me>

ChihweiLHBird force-pushed the zhiwei/otel-semantic-conventions branch from f8bb3c1 to 900797a Compare May 14, 2026 16:42

Adopt opentelemetry-semantic-conventions for OTel attribute names

e3e19ef

Signed-off-by: Zhiwei Liang <zhiwei.liang@zliang.me>

ChihweiLHBird force-pushed the zhiwei/otel-semantic-conventions branch from 900797a to e3e19ef Compare May 14, 2026 17:13

lann requested a review from calebschoepp May 14, 2026 17:29

itowlson requested a review from lann May 15, 2026 00:29

calebschoepp reviewed May 15, 2026

View reviewed changes

Use OTel semconv constants for HTTP span fields

2424006

Signed-off-by: Zhiwei Liang <zhiwei.liang@zliang.me>

ChihweiLHBird force-pushed the zhiwei/otel-semantic-conventions branch from 7f046d0 to 2424006 Compare May 15, 2026 15:56

ChihweiLHBird requested a review from calebschoepp May 15, 2026 16:15

Refactor to use OpenTelemetry attribute aliasing for HTTP span fields

0b5917b

Updated the usage of OpenTelemetry semantic conventions in the outbound HTTP crate to utilize the new aliasing for attribute names. Signed-off-by: Zhiwei Liang <zhiwei.liang@zliang.me>

Conversation

ChihweiLHBird commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

lann commented May 14, 2026

Uh oh!

ChihweiLHBird commented May 14, 2026

Uh oh!

lann commented May 14, 2026

Uh oh!

ChihweiLHBird commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lann commented May 14, 2026

Uh oh!

ChihweiLHBird commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChihweiLHBird commented May 15, 2026

Uh oh!

calebschoepp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChihweiLHBird May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChihweiLHBird May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lann May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChihweiLHBird commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lann commented May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ChihweiLHBird commented May 14, 2026 •

edited

Loading

ChihweiLHBird commented May 14, 2026 •

edited

Loading

ChihweiLHBird commented May 14, 2026 •

edited

Loading

ChihweiLHBird May 15, 2026 •

edited

Loading

ChihweiLHBird May 15, 2026 •

edited

Loading

lann May 15, 2026 •

edited

Loading

ChihweiLHBird commented May 15, 2026 •

edited

Loading