Crate forge_ops_tracker 

ForgeOps error tracking client for ForgeOps:

forge_ops_tracker::init(|c| {
    c.dsn = Some("https://<api_key>@getforgeops.net/api/v1/events".to_string());
});

See the README for what gets captured automatically vs. what needs an explicit capture_error call. A from-scratch port of gems/forge_ops_tracker (the Rails client): see that gem’s README for the shared design rationale behind the pieces this crate is built from (Configuration, EventBuilder, DeliveryQueue, Reporter, Client).

Macros

context

Builds a HashMap<String, Value> from key => value pairs, the same literal-context ergonomics every other client in this repo gets for free from its own language (a Python dict, a JS object literal, a PHP array):

Structs

Breadcrumb

One entry in a trail. Matches the wire shape gems/forge_ops_tracker’s own BreadcrumbBuffer#add already builds, and the same four keys Api::V1::EventsController permits.

Configuration

Holds a single ForgeOps DSN plus everything else the client needs to build and deliver events. Mirrors gems/forge_ops_tracker’s Configuration: a single DSN string carries both the ingestion URL and the project’s API key: “https://<api_key>@host/api/v1/events”.

Event

Frame

SqlObjects

What extraction found in a statement: its operation (the first keyword), the stored procedures/functions it called, and the tables/views it touched. A view and a table are written the same way in SQL text, so both land in relations.

Enums

TracePropagationTarget

One entry in Configuration.trace_propagation_targets. Build one with .into() from a &str or String (a host) or a regex::Regex:

Value

A JSON-like value: what context/tags are built out of. Hand-rolled rather than depending on serde_json’s Value: this crate already needs regex/backtrace/ureq for things Rust’s standard library genuinely lacks (see README.md’s “Dependencies” section), and a fourth dependency purely for a value type this small isn’t worth it.

Constants

TRACEPARENT_HEADER

The name of the W3C Trace Context header: what continue_trace reads from an incoming request and what http_span’s value goes out as.

Traits

ResultReportExt

Extension trait for Result, so a fallible call can report its own error and still propagate it in one step:

Functions

add_breadcrumb

Records one entry into the current thread’s breadcrumb trail: a query, an outbound call, or anything worth remembering right up to the moment something actually goes wrong. category defaults to "custom" and level to "info" when passed an empty string. A no-op, not an error, when Configuration.track_breadcrumbs is false.

capture_error

Reports an error you’ve already handled. Call it right at the point you’d otherwise just log it:

capture_error_with_class

The same as capture_error, but for a &dyn std::error::Error (a Box<dyn Error>, a trait object) whose concrete type isn’t known at the call site, so exception_class has to be supplied explicitly rather than inferred.

capture_error_with_class_and_sql

The same as capture_error_with_sql, but for a &dyn std::error::Error whose concrete type isn’t known at the call site, so exception_class is supplied explicitly.

capture_error_with_sql

The same as capture_error, for an error caused by a database call: pass the SQL that ran. A Rust error carries no statement of its own and no Rust database crate puts one on its error types, so the code that ran the query has to hand it over.

capture_infrastructure_metric

Records one infrastructure reading (CPU, memory, disk, anything else a program of yours reads) from one of your own hosts. hostname defaults to Configuration.server_name when None, so a script running on the box it reports about needs no argument. Same buffered-batch delivery and no-op-when-disabled contract as capture_metric.

capture_metric

Records a named business metric (a signup, a payment, anything you want to name), buffered and flushed periodically as one batch rather than one network call per capture. Pass 1.0 for a bare counter-style call (“a signup happened”) or a real magnitude (“a $49 payment”); it may be negative (a refund). A no-op when the client isn’t enabled (no DSN, or this environment isn’t in enabled_environments), and a NaN or infinite value is dropped.

clear_breadcrumbs

Clears the current thread’s breadcrumb trail. See add_breadcrumb’s own doc for why calling this yourself, at the start of each request, is this crate’s responsibility to ask of you rather than something it can do on its own.

continue_trace

The same as trace, continuing the caller’s trace when traceparent is a usable W3C traceparent header value, typically the incoming request’s own header: the trace keeps the caller’s trace id, and its root span records the caller’s span as its parent, so it nests under that span on ForgeOps. None, blank, or malformed starts a fresh trace, exactly like trace. Ignored inside an already-open trace.

current_trace_id

The id of the trace open on this thread (32 lowercase hex characters), or None outside a trace. Errors captured on this thread while it’s open carry it automatically.

flush_metrics

Delivers every buffered metric and infrastructure reading right now, instead of waiting for the next flush interval. The background flush thread is a daemon and Rust has no exit hook, so call this before a short-lived program ends.

flush_performance

Delivers whatever has been tallied so far right now, instead of waiting for the next performance_flush_interval tick. The background flush thread is a daemon: it does not run on a normal process exit the way the Ruby gem’s at_exit hook does (Rust has no equivalent), so a short-lived program, or one about to shut down, should call this itself to avoid losing the last partial window.

http_span

Times an outgoing HTTP call as an http span named "<METHOD> <host>" (never the path or query, which can carry ids or tokens) and hands f the traceparent header value to send with that request: its parent id is this span’s own id, so the called service’s root span nests under it when it continues the trace. Set it however your HTTP client does:

init

Configures the client. Call once at startup, before your server starts accepting requests. Pass a closure to set any Configuration field:

install_panic_hook

Installs a global panic hook that reports any panic on any thread, then calls whatever hook was previously installed (Rust’s own default, which prints to stderr, unless something else already replaced it): never changing panic behavior itself, the same “report, then don’t change program behavior” rule the .NET middleware and Python excepthook wrapper both follow.

record_performance

Records one timed call’s duration, in milliseconds, under transaction_name: tallied in-process (count, total, max) and flushed periodically as one small aggregate report, for the Performance page’s per-transaction table, not one network call per call. A no-op when Configuration.track_performance is false or reporting isn’t enabled for this environment.

record_span

Records a span you timed yourself under the current one; a no-op outside a trace.

set_user

Manually attaches an affected user to whatever gets reported from here on, on this thread (an explicit capture_error/capture_error_with_class call with no user argument, or a panic the installed hook catches): there’s no way to automatically detect “the current user” the way a server-side web framework with its own session/auth middleware can, so call this yourself, e.g. right after sign-in. id/email/username are all independently optional; call with an empty map to clear whatever was set, e.g. on sign-out. See this crate’s own CURRENT_USER thread-local (in the source) for why this is thread-local, and the real caveat that comes with that choice under an async runtime.

span

Times f as a child span of whatever span is open on this thread (or of the trace’s root), returning what f returned. Outside a trace it just runs f. Recorded even if f panics. kind is one of "controller", "service", "database", "redis", "http", "job", "other" (anything else is sent as "other").

time_transaction

Runs f, records how long it took under transaction_name (see record_performance), and returns whatever f returned. Recorded even if f panics: the duration up to the panic is still a real duration, and a handler that panics is exactly one worth seeing on the Performance page.

trace

Runs f as a trace named root_name (for example "GET /checkout" or "job:reindex"): every span, http_span and record_span inside it, on this thread, nests beneath this root. When f took at least Configuration.trace_capture_threshold (1 second by default) the whole trace is sent to ForgeOps, so fast calls cost nothing on the wire. Sent even if f panics. Called inside an already-open trace it just records a span instead. Errors captured inside it carry its trace id (see current_trace_id).