ITelemetryService class abstract

Simplified interface for telemetry service operations.

Provides methods for starting/ending traces, spans, and recording metrics. Methods return Future<void> for async operations that interact with the repository.

Architecture

This service follows the Clean Architecture pattern:

Usage Example

final telemetry = SimpleTelemetryService(mockRepository);

// Start a trace for database operation
final trace = telemetry.startTrace('database.query');

// Execute query and record metrics
await telemetry.recordMetric(
  name: 'query.count',
  metricType: 'counter',
  value: 1,
);

// End trace when operation completes
await telemetry.endTrace(traceId: trace.traceId);

Thread Safety

IMPORTANT: Trace and Span returned by startTrace/startSpan are NOT thread-safe. Do NOT share across isolates. Always create new Trace/Span objects within the same isolate that needs them.

Key Features

  • Tracing: Distributed tracing with parent-child relationships
  • Metrics: Counters, gauges, and histograms
  • Events: Log entries with severity levels
  • Auto-batching: Automatic buffer flushing at intervals
  • Error Handling: Repository handles errors internally; service does not need to catch
Implementers

Constructors

ITelemetryService()

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
serviceName → String
Service name identifier.
no setter

Methods

endSpan({required String spanId, Map<String, String> attributes = const {}}) → Future<void>
Finishes a span with optional attributes.
endTrace({required String traceId, Map<String, String> attributes = const {}}) → Future<void>
Finishes a trace with optional attributes.
flush() → Future<void>
Flushes all pending telemetry data.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
recordEvent({required String name, required TelemetrySeverity severity, required String message, Map<String, dynamic> context = const {}}) → Future<void>
Records a telemetry event (log entry).
recordGauge({required String name, required double value, Map<String, String> attributes = const {}}) → Future<void>
Records a gauge metric (current value).
recordMetric({required String name, required String metricType, required double value, String unit = 'count', Map<String, String> attributes = const {}}) → Future<void>
Records a counter metric.
recordTiming({required String name, required Duration duration, Map<String, String> attributes = const {}}) → Future<void>
Records a timing metric.
shutdown() → Future<void>
Shutdowns telemetry exporter and releases resources.
startSpan({required String parentId, required String spanName, Map<String, String> initialAttributes = const {}}) → Span
Creates a child span within a trace.
startTrace(String operationName) → Trace
Starts a new distributed trace.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited