Observability Decorators
Define TypeScript tracing, metrics, structured logging, health checks, SLOs, critical execution paths, and telemetry sampling with AxilJS semantic decorators.
On this page9
Observability decorators declare telemetry behavior at the method level. They reduce instrumentation boilerplate while allowing an observability consumer to handle the underlying telemetry mechanics.
@tTrace
tTrace declares a distributed trace span around a method.
1import { tTrace } from '@axiljs/decorator'
2
3@tTrace('checkout-flow')
4async checkout(orderId: string) {}
5
6@tTrace('db-query', {
7 tags: { table: 'users' },
8})
9async findUser(id: string) {}The trace name identifies the operation, while optional tags provide additional metadata for the trace.
@tMetric
tMetric records a metric for each invocation.
1@tMetric('orders.created', 'counter')
2async createOrder() {}
3
4@tMetric('search.duration', 'histogram', {
5 buckets: [10, 50, 100, 500],
6})
7async search(query: string) {}AxilJS supports the following metric types:
| Type | Description |
|---|---|
'counter' | Monotonically increasing count |
'gauge' | Point-in-time value |
'histogram' | Distribution of values |
'summary' | Quantile-based distribution |
@tLog
tLog emits structured log entries at method boundaries.
1@tLog('info', {
2 includeArgs: true,
3})
4async createUser(dto: CreateUserDto) {}
5
6@tLog('warn', {
7 message: 'Payment retry',
8 includeError: true,
9})
10async retryPayment() {}This allows logging intent and relevant context to be declared alongside the operation instead of embedding instrumentation throughout the business logic.
@tHealthCheck
tHealthCheck registers a method as a health-check probe.
1@tHealthCheck('database')
2async checkDatabase() {
3 await this.db.ping()
4
5 return {
6 status: 'up',
7 }
8}The decorator identifies the operation as a health-check probe; the method provides the actual check.
@tSlo
tSlo declares a service-level objective for an operation.
1@tSlo({
2 latency: 300,
3 percentile: 99,
4})
5async getUser() {}This expresses the expected latency objective and percentile as semantic metadata.
@tCritical
tCritical marks a method as a critical execution path for elevated monitoring.
@tCritical()
async processPayment() {}This is useful for operations where failures or performance degradation require increased monitoring attention.
@tSample
tSample controls telemetry sampling for high-volume operations.
1@tSample({
2 rate: 0.1,
3})
4async healthCheck() {}A sampling rate of 0.1 declares a 10% telemetry sampling rate for the operation.
Full Observability Stack
Observability semantics can be composed with HTTP and request metadata:
1@tHttp({
2 method: 'POST',
3 path: '/checkout',
4})
5@tTrace('checkout', {
6 tags: { critical: true },
7})
8@tMetric('checkout.started', 'counter')
9@tSlo({
10 latency: 500,
11 percentile: 99,
12})
13@tCritical()
14@tLog('info', {
15 includeArgs: true,
16})
17async checkout(@tBody() dto: CheckoutDto) {
18 return this.checkoutService.process(dto)
19}One method can therefore declare its API contract, distributed tracing, metrics, latency objective, criticality, and structured logging requirements without embedding those concerns directly into the business operation.
Reference
| Decorator | Purpose |
|---|---|
tTrace | Declare distributed tracing |
tMetric | Record operation metrics |
tLog | Emit structured logs |
tHealthCheck | Register a health-check probe |
tSlo | Declare a service-level objective |
tCritical | Mark a critical execution path |
tSample | Control telemetry sampling |
These decorators are semantic declarations. The metadata can be consumed by an observability implementation rather than coupling application code directly to a particular telemetry provider. AxilJS's consumer model separates metadata declaration from runtime behavior.
Was this page helpful?