Skip to content

feat(stackable-telemetry)!: Record HTTP server request duration - #1333

Open
lfrancke wants to merge 3 commits into
telemetry-metricsfrom
telemetry-http-semconv
Open

lfrancke wants to merge 3 commits into
telemetry-metricsfrom
telemetry-http-semconv

Conversation

@lfrancke

@lfrancke lfrancke commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Description

This builds on #1332 to amend the AxumTraceLayer to also record the http.server.request.duration as a metric. It uses the HTTP metric semantic conventions including the bucket sizes. Spans and metrics now reuse the same method, scheme, route and protocol.

Breaking, span output and API:

  • An unknown request method is recorded as _OTHER with the original in http.request.method_original, and the span name starts with HTTP, as the span conventions require. Before this change, arbitrary client-sent methods became span names (not good).
  • url.scheme is the scheme set with with_url_scheme instead of the request URI's scheme, which is empty for the usual origin-form request.
  • network.protocol.version is recorded.

All other span attributes are unchanged.

Definition of Done Checklist

  • Not all of these items are applicable to all PRs, the author should update this template to only leave the boxes in that are relevant
  • Please make sure all these things are done and tick the boxes

Reviewer

  • Code contains useful comments
  • Code contains useful logging statements
  • Changelog updated

Acceptance

  • Proper release label has been added

@lfrancke
lfrancke added this pull request to stack #1334 November 16, 2026 22:26
@lfrancke
lfrancke force-pushed the telemetry-http-semconv branch from de41e8e to 216152e Compare November 16, 2026 22:28
@lfrancke lfrancke self-assigned this Nov 16, 2026
@lfrancke lfrancke moved this to Development: Waiting for Review in Stackable Engineering Nov 16, 2026
@lfrancke
lfrancke marked this pull request as ready for review November 16, 2026 22:36
@lfrancke
lfrancke force-pushed the telemetry-http-semconv branch from 216152e to a67c828 Compare November 17, 2026 09:20
Comment on lines +19 to +20
/// The value recorded for an HTTP method the conventions do not list as known.
pub const OTHER_METHOD: &str = "_OTHER";

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could probably just not return the key if it is invalid.
And if invalid, the server shouldn't be handling it anyway, so it does seem useful in telemetry.

I will have to do out an example, but there is a nice way to handle Option, so that the value isn't None or Some("GET"), but rather not present at all, or GET.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reason this is here is because http.request.method is required according to the semantic conventions: https://opentelemetry.io/docs/specs/semconv/http/http-metrics/

Comment on lines +31 to +45
pub fn http_request_method(method: &Method) -> &'static str {
match *method {
Method::CONNECT => "CONNECT",
Method::DELETE => "DELETE",
Method::GET => "GET",
Method::HEAD => "HEAD",
Method::OPTIONS => "OPTIONS",
Method::PATCH => "PATCH",
Method::POST => "POST",
Method::PUT => "PUT",
Method::TRACE => "TRACE",
_ if method.as_str() == "QUERY" => "QUERY",
_ => OTHER_METHOD,
}
}

@NickLarsenNZ NickLarsenNZ Nov 20, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this not already implemented on http::Method (I believe axum re-exports the http crate)? Might be gated behind a feature.
Just curious.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. I asked the same question because I couldn't really believe it and probably should have left a comment here (and I have a feeling we had the same discussion before in the company...)

https://docs.rs/http/latest/http/method/struct.Method.html
It only has as_str but that a) borrows from Method and b) doesn't support _OTHER

If you find one that both me and Claude missed I'd be happy. This feels dirty.

Comment on lines +49 to +58
pub fn network_protocol_version(version: Version) -> Option<&'static str> {
match version {
Version::HTTP_09 => Some("0.9"),
Version::HTTP_10 => Some("1.0"),
Version::HTTP_11 => Some("1.1"),
Version::HTTP_2 => Some("2"),
Version::HTTP_3 => Some("3"),
_ => None,
}
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here (about this being implemented on http::Version)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, btw, quite often HTTP_2 will be called h2, and I can't remember what HTTP_3 gets called (maybe h3?).

Not a major, but maybe we want to look up to see if there are conventions defined.


Edit: leaving the comment here, but I found the answer:

image

as you were

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Version has a different problem than Method but also nothing usable.

It only has Debug which I wouldn't rely on even though it's probably stable https://docs.rs/http/latest/http/version/struct.Version.html - that said it'd also return the wrong string: https://docs.rs/http/latest/src/http/version.rs.html#62-75

Comment on lines +60 to +70
/// Returns the `http.route` value: the route template axum matched, never the raw path.
///
/// Axum inserts [`MatchedPath`] while routing, so it is only present for a layer added through
/// `Router::layer` or `Router::route_layer`, and only for requests a route matched. A layer that
/// wraps the whole `Router` as a service, and the router's fallback, see no route.
pub fn http_route(request: &Request) -> Option<&str> {
request
.extensions()
.get::<MatchedPath>()
.map(MatchedPath::as_str)
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might want make some traits for extending these types. So for now, we should maybe make this (and others) pub(crate) so we don't break the API straight away if we do.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. I didn't even think about that.

fe0d2c4 (this PR)

Comment on lines +115 to +125
/// `http.request.method`, see [`http_request_method`].
pub method: &'static str,

/// `url.scheme`.
pub scheme: &'static str,

/// `http.route`, see [`http_route`].
pub route: Option<String>,

/// `network.protocol.version`, see [`network_protocol_version`].
pub protocol_version: Option<&'static str>,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Depending on what guarantees we want to give with this public type, we might want to keep the fields private (to prevent invalid construction/mutation).

Eg: If I had a ServerRequestAttributes, I (or any user of this crate) could change it in a way that's hard to guard against, making the construction checks ineffective.

let request: Request = ...; // some request that I get

let sra = ServerRequestAttributes::from_request(&request);
// At this point, we have a valid SRA.
// But now I can create an invalid state:
let mut sra = sra;
sra.protocol_version = Some("https://www.youtube.com/watch?v=dQw4w9WgXcQ"); // not a valid protocol version.

So that then means all usages of it have to then verify (we want encouraging Parse-don't-verify).

@lfrancke lfrancke Nov 20, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, done in fe0d2c4 (this PR) by removing all the pubs and creating methods instead.

Total side question: There is no such concept as "properties" in Rust, right? Or being discussed where these kinds of accessor methods are created automatically?

@NickLarsenNZ NickLarsenNZ left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another partial review. I will really try and get onto this on Monday.

I'll mainly try to cover the public API of the types, and whether we are allowing invalid states. The rest would be optional nit-picks (we can easily change private internals).

@lfrancke

Copy link
Copy Markdown
Member Author

This is really and honestly not urgent. But thank you for the review.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Development: Waiting for Review

Development

Successfully merging this pull request may close these issues.

2 participants