feat(macro): add macros to trace error including stack, trace and backtrace

[damjack]

Hi, I would like to propose to add macros to make it easy to record and emit errors to tracing spans and events while including structured error data, the error chain (source), and a stack/backtrace.
The new macros reduce boilerplate when converting Result/Errors into tracing events, attaching contextual fields (error, cause chain, span/trace ids), and capturing a Backtrace when the feature is enabled.

So in short what I would like to have is:

use prima_tracing::trace_error;

fn main {
	let error = some_fallible()?;

	trace_error(error, "custom message that is visibile as trace error message")
}

One plus I added is to handle also anyhow error crate:

# Cargo.toml

prima-tracing = { version = "0.18" features = ["traces", "anyhow"] }

use anyhow:anyhow
use prima_tracing::trace_anyhow_error;

fn main {
	let error = anyhow("the anyhow error");

	trace_anyhow_error(error, "custom message that is visibile as trace error message")
}

Motivation

• Developers commonly need to log/trace errors with context (message, error chain, where it occurred). Doing this manually is repetitive and error-prone.
• Capturing a backtrace or stack at the site an error is handled can be invaluable for debugging.
• These macros make consistent, structured error tracing the default pattern across the codebase.

Tests & docs

• Added unit tests that assert that:
  • Events include the expected fields (error message, error type, cause chain).
  • Backtrace data is attached.
  • Span and trace identifiers are included when a span is active.
• Documentation includes short examples and notes about feature flags and performance considerations.

[cpiemontese]

Hey, not sure what that the intermediaries code contains and how intermediaries-specific it is, but if it can enrich prima_tracing.rs why not

[damjack]

Hey, not sure what that the intermediaries code contains and how intermediaries-specific it is, but if it can enrich prima_tracing.rs why not

I'm trying to decide whether to implement everything here or use an existing crate that does the same thing, like this one.

[cpiemontese]

Using something existing sounds very enticing tbh 😁 Not sure how the features compare with the custom lib

[cpiemontese]

I see the CI is still red, will #157 fix it?

[damjack]

I see the CI is still red, will #157 fix it?

Yeah, I just rebase from master

[cpiemontese]

Added some comments, mostly related to typos

In general, looking at the otel semconvs it seems like this is fine, most of these fields are custom to us (e.g. stack is not part of the error semconv)

Also, I don't know how much Datadog care about this semconvs

For the actual macros, I will give time to someone else to review since I'm not really familiar with them

[cpiemontese]

I still don't understand what these definitions import, are these internal crates?

[damjack]

I'll try to explain them.

error-report -> https://docs.rs/error-report/0.0.1/error_report

Report prints an error and all its sources.

Source messages will be cleaned using CleanedErrors to remove duplication from errors that include their source’s message in their own message.

The debug implementation prints each error on a separate line, while the display implementation prints all errors on one line separated by a colon. Using alternate formatting ({:#}) is identical to the debug implementation.

tracing-capture -> https://docs.rs/tracing-capture/0.1.0/tracing_capture/

This crate provides a tracing Layer to capture tracing spans and events as they occur.

The captured spans and events can then be used for testing assertions (e.g., "Did a span with a specific name / target / … occur? What were its fields? Was the span closed? How many times the span was entered?" and so on).

[MatteoJoliveau]

Word of advise @damjack , the error-report crate used in starsky and incentives-backend is not https://docs.rs/error-report, but https://github.com/primait/intermediaries-crates/tree/master/error-report

[cpiemontese]

Thanks for the reference

I see tracing_capture is just imported in tests, is it just a local dev library?

For error-report the fact that

• it is 0.0.1
• has no associated repo
  kinda scares me off of depending on it, could the code be ported directly here...?

Not sure if we need everything contained in the source, I get wanting to "pretty print" errors but we already depend on shaky libs as is