iet-telemetry

core contracts official

Defines bounded operation identities and recording that compiles to a no-op by default.

CoreFeaturesIntegrationsStacksTooling

Used byiet-auth-acliet-auth-acl-timescaleiet-auth-basiciet-auth-basic-timescaleiet-auth-login-htmx-axumiet-auth-profiles-timescaleiet-auth-rbaciet-auth-rbac-timescale+11 more

iet-telemetrycontractsTelemetry contracts

Depends oniet-corecontractiet-configcontract

How to use it

iet-telemetry records operation timings and lifecycle outcomes under a bounded, implementation-owned identity, and provides TelemetryConfig/Profile for exporter settings. Operation::record wraps a future, Stage wraps a blocking section, and Noop is a concrete no-op recorder; enabled() gates all work behind the recording feature and an accepting subscriber.

rust

// examples/htmx-starter/crates/project-impl-timescale/src/service.rs
use iet_telemetry::Operation;

// Static vocabulary only: component/name/operation, never customer IDs or cache keys.
let result = Operation::new("service", "project", "create")
    .record(async {
        // ... do the work and return AppResult<()>
        Ok::<_, iet_core::AppError>(())
    })
    .await?;

Use .lifecycle(future) when you want start/finish/cancel logging even without metric recording; a dropped Stage records cancelled.
With the recording feature off, record/lifecycle forward the future directly: no clock read, span, or subscriber lookup.

How it works

Operation::record wraps the caller's future, and when recording is compiled in and enabled it opens a Stage that emits fw_operation_active, completion counters, and a duration histogram through tracing.

sequenceDiagram
  participant C as "Caller"
  participant O as "Operation"
  participant E as "enabled"
  participant S as "Stage"
  participant T as "tracing events"
  C->>O: "new component name operation"
  C->>O: "record future"
  O->>E: "recording_compiled"
  alt enabled
    O->>S: "start"
    S->>T: "fw_operation_active"
    O->>S: "finish result"
    S->>T: "duration and outcome"
  end
  O-->>C: "Result"

Core contract

This page is the crate reference. For the framework-wide runtime and trait model, read Architecture.

What it implements

Core contracts and primitives; see the public API below.

What's inside

Modules

src/config.rs
src/lib.rs

Public API

(root)

pub fn enabled() -> bool
const fn
struct Operation
pub fn record_sync<T, E>(self, action: impl FnOnce() -> Result<T, E>) -> Result<T, E> — Blocking operations keep concrete dispatch and cancellation/error accounting.
const fn
const fn
pub fn start(self) -> Stage
struct Noop
struct Stage — Stack-owned timer; cancellation is recorded if dropped before completion.
pub fn new(name: &'static str) -> Self
pub fn operation(identity: Operation) -> Self
pub fn finish<T, E>(mut self, result: &Result<T, E>)
pub fn finish_outcome(mut self, outcome: &'static str)

config

enum HistogramConfig
pub fn valid(&self) -> bool
enum Profile
struct TelemetryConfig
pub fn profile(profile: Profile) -> Self
pub fn validate(&self) -> AppResult<()>

Impl map

Default for HistogramConfig
FromStr for Profile
Default for TelemetryConfig
Configuration for TelemetryConfig
Drop for LifecycleCompletion
Drop for Stage

Depends on

External crates: tracing

Cargo features

default — (no dependencies)
recording — (no dependencies)

Used by

In this repository

examples/htmx-starter

Source: crates/core/iet-telemetry