Observability Decorators

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.

import { tTrace } from '@axiljs/decorator'
 
@tTrace('checkout-flow')
async checkout(orderId: string) {}
 
@tTrace('db-query', {
  tags: { table: 'users' },
})
async 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.

@tMetric('orders.created', 'counter')
async createOrder() {}
 
@tMetric('search.duration', 'histogram', {
  buckets: [10, 50, 100, 500],
})
async search(query: string) {}

AxilJS supports the following metric types:

@tLog#

tLog emits structured log entries at method boundaries.

@tLog('info', {
  includeArgs: true,
})
async createUser(dto: CreateUserDto) {}
 
@tLog('warn', {
  message: 'Payment retry',
  includeError: true,
})
async 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.

@tHealthCheck('database')
async checkDatabase() {
  await this.db.ping()
 
  return {
    status: 'up',
  }
}

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.

@tSlo({
  latency: 300,
  percentile: 99,
})
async 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.

@tSample({
  rate: 0.1,
})
async 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:

@tHttp({
  method: 'POST',
  path: '/checkout',
})
@tTrace('checkout', {
  tags: { critical: true },
})
@tMetric('checkout.started', 'counter')
@tSlo({
  latency: 500,
  percentile: 99,
})
@tCritical()
@tLog('info', {
  includeArgs: true,
})
async checkout(@tBody() dto: CheckoutDto) {
  return this.checkoutService.process(dto)
}

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#

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.