feat: Add observability package

Author: dnys1

packages/observability/.gitignore

@@ -0,0 +1,7 @@
+# https://dart.dev/guides/libraries/private-files
+# Created by `dart pub`
+.dart_tool/
+
+# Avoid committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock

packages/observability/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- Initial version.

packages/observability/LICENSE

@@ -0,0 +1,46 @@
+Copyright (c) 2025 The Celest project authors
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+Subject to the terms and conditions of this license, each copyright holder and
+contributor hereby grants to those receiving rights under this license a
+perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except for failure to satisfy the conditions of this license) patent license to
+make, have made, use, offer to sell, sell, import, and otherwise transfer this
+software, where such license applies only to those patent claims, already
+acquired or hereafter acquired, licensable by such copyright holder or
+contributor that are necessarily infringed by:
+
+(a) their Contribution(s) (the licensed copyrights of copyright holders and
+non-copyrightable additions of contributors, in source or binary form) alone; or
+
+(b) combination of their Contribution(s) with the work of authorship to which
+such Contribution(s) was added by such copyright holder or contributor, if, at
+the time the Contribution is added, such addition causes such combination to be
+necessarily infringed. The patent license shall not apply to any other
+combinations which include the Contribution.
+
+Except as expressly stated above, no rights or licenses from any copyright
+holder or contributor is granted under this license, whether expressly, by
+implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/observability/README.md

@@ -0,0 +1,90 @@
+## Observability
+
+Utilities for instrumenting Celest services with structured metrics and
+lightweight tracing primitives. The package is backend agnostic; plug in your
+preferred recorder or tracer implementation and forward data to systems such as
+Prometheus, OpenTelemetry, or Honeycomb.
+
+## Features
+
+- Thin abstractions for counters and histograms with structured attribute maps.
+- Global registries (`GlobalMetrics`, `GlobalTracer`) for late-bound DI wiring.
+- Helper APIs for measuring latency and running traced closures.
+
+## Getting started
+
+Add the dependency to your `pubspec.yaml` (most Celest repositories already do
+this):
+
+```yaml
+dependencies:
+  observability:
+    path: ../../packages/observability
+```
+
+Install your recorder/tracer early during service start-up:
+
+```dart
+Future<void> bootstrap() async {
+  final recorder = PrometheusRecorder(/* config */);
+  GlobalMetrics.install(MetricsRegistry(recorder: recorder));  
+  
+  final tracer = OpenTelemetryTracer(/* config */);
+  GlobalTracer.install(TracerRegistry(tracer: tracer));
+  }
+```
+
+## Usage
+
+Create structured helpers when emitting metrics:
+
+```dart
+final StructuredCounter requestCounter = StructuredCounter(
+  recorder: GlobalMetrics.instance.recorder,
+  name: 'http_requests_total',
+  description: 'Requests grouped by method.',
+);
+
+requestCounter.increment(attributes: {'method': 'GET'});
+```
+
+Measure latency without hand-rolled stopwatches:
+
+```dart
+final histogram = GlobalMetrics.instance.recorder.histogram(
+  'db_latency_ms',
+  description: 'Database round-trip latency in milliseconds.',
+);
+
+await recordLatency(
+  histogram: histogram,
+  attributes: {'operation': 'insert'},
+  run: () async => await db.insert(row),
+);
+```
+
+Wrap business logic in spans to collect trace data:
+
+```dart
+await GlobalTracer.instance.tracer.trace<void>(
+  name: 'orders.create',
+  attributes: {'route': '/v1/orders'},
+  run: (span) async {
+  	span.addEvent('validation.start');
+  	await orderValidator.validate(payload);
+  	span.addEvent('validation.complete');
+  	span.setStatus(SpanStatus.ok);
+  },
+);
+```
+
+## Example
+
+A runnable example that prints metrics and spans to stdout lives under
+[`example/observability_example.dart`](example/observability_example.dart).
+
+## Contributing
+
+File issues and PRs in the main [celest](https://github.com/celest-dev/celest)
+repository. Please include relevant logs or traces when reporting
+observability-related bugs.

packages/observability/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:celest_lints/library.yaml

packages/observability/example/observability_example.dart

@@ -0,0 +1,158 @@
+// ignore_for_file: avoid_print, omit_obvious_local_variable_types
+
+import 'dart:async';
+
+import 'package:observability/observability.dart';
+
+/// Simple example that wires up custom metric and tracing recorders and emits
+/// a few demo signals. In a production setting these recorders would forward
+/// data to systems such as OpenTelemetry, Prometheus, or Honeycomb.
+Future<void> main() async {
+  // Install global registries so framework code can locate the recorders.
+  GlobalMetrics.install(MetricsRegistry(recorder: _PrintMetricRecorder()));
+  GlobalTracer.install(TracerRegistry(tracer: _PrintTracer()));
+
+  final MetricRecorder recorder = GlobalMetrics.instance.recorder;
+
+  // Create structured helpers that attach consistent attributes.
+  final StructuredCounter requestCounter = StructuredCounter(
+    recorder: recorder,
+    name: 'example_requests_total',
+    description: 'Number of demo requests by method.',
+  );
+
+  final StructuredCounter cacheCounter = StructuredCounter(
+    recorder: recorder,
+    name: 'example_cache_outcome_total',
+    description: 'Cache results grouped by outcome.',
+  );
+
+  final Histogram latencyHistogram = recorder.histogram(
+    'example_request_latency_ms',
+    description: 'Latency for demo request handling in milliseconds.',
+  );
+
+  final Tracer tracer = GlobalTracer.instance.tracer;
+
+  // Emit observability signals around some fake work.
+  await tracer.trace<void>(
+    name: 'example.request',
+    attributes: {'route': '/hello', 'method': 'GET'},
+    run: (Span span) async {
+      requestCounter.increment(attributes: {'method': 'GET'});
+
+      await recordLatency(
+        histogram: latencyHistogram,
+        attributes: {'route': '/hello'},
+        run: () async {
+          span.addEvent('work.started');
+          await Future<void>.delayed(const Duration(milliseconds: 12));
+          span.addEvent('work.finished');
+        },
+      );
+
+      cacheCounter.increment(attributes: {'outcome': 'miss'});
+
+      span.setStatus(SpanStatus.ok);
+    },
+  );
+}
+
+class _PrintMetricRecorder implements MetricRecorder {
+  @override
+  Counter counter(String name, {String? description}) {
+    return _PrintCounter(name, description: description);
+  }
+
+  @override
+  Histogram histogram(String name, {String? description}) {
+    return _PrintHistogram(name, description: description);
+  }
+}
+
+class _PrintCounter implements Counter {
+  _PrintCounter(this.name, {this.description});
+
+  final String name;
+  final String? description;
+
+  @override
+  void add(num value, {Map<String, String>? attributes}) {
+    print(
+      'counter<$name>${description != null ? ' ($description)' : ''}: '
+      'value=$value attributes=$attributes',
+    );
+  }
+}
+
+class _PrintHistogram implements Histogram {
+  _PrintHistogram(this.name, {this.description});
+
+  final String name;
+  final String? description;
+
+  @override
+  void record(num value, {Map<String, String>? attributes}) {
+    print(
+      'histogram<$name>${description != null ? ' ($description)' : ''}: '
+      'value=$value attributes=$attributes',
+    );
+  }
+}
+
+class _PrintTracer extends Tracer {
+  @override
+  Span startSpan(
+    String name, {
+    SpanContext? parent,
+    Map<String, Object?>? attributes,
+  }) {
+    print('span<$name> start attributes=$attributes');
+    return _PrintSpan(name, parent: parent);
+  }
+}
+
+class _PrintSpan implements Span {
+  _PrintSpan(this.name, {SpanContext? parent}) : _context = _derive(parent);
+
+  final String name;
+  final SpanContext _context;
+  SpanStatus _status = SpanStatus.unset;
+
+  @override
+  SpanContext get context => _context;
+
+  @override
+  void addEvent(String eventName, {Map<String, Object?>? attributes}) {
+    print('span<$name> event=$eventName attributes=$attributes');
+  }
+
+  @override
+  void end({SpanStatus status = SpanStatus.unset}) {
+    _status = status == SpanStatus.unset ? _status : status;
+    print('span<$name> end status=$_status');
+  }
+
+  @override
+  void recordError(Object error, StackTrace stackTrace) {
+    print('span<$name> error=$error stackTrace=$stackTrace');
+    _status = SpanStatus.error;
+  }
+
+  @override
+  void setAttribute(String key, Object? value) {
+    print('span<$name> attr $key=$value');
+  }
+
+  @override
+  void setStatus(SpanStatus status, {String? description}) {
+    _status = status;
+    print('span<$name> status=$status description=$description');
+  }
+
+  static SpanContext _derive(SpanContext? parent) {
+    final String traceId = parent?.traceId ?? 'example-trace';
+    final String spanId = DateTime.now().microsecondsSinceEpoch.toString();
+    return SpanContext(traceId: traceId, spanId: spanId);
+  }
+}

packages/observability/lib/observability.dart

@@ -0,0 +1,11 @@
+// ignore_for_file: unnecessary_library_name
+
+/// Observability primitives for Celest services.
+library observability;
+
+export 'src/counters.dart';
+export 'src/histograms.dart';
+export 'src/logging.dart';
+export 'src/metrics.dart';
+export 'src/registry.dart';
+export 'src/tracing.dart';

packages/observability/lib/src/counters.dart

@@ -0,0 +1,38 @@
+import 'package:observability/src/metrics.dart';
+
+/// A convenience wrapper around [Counter] that standardises metric creation and
+/// exposes expressive helper methods.
+///
+/// Typical usage installs a [MetricRecorder] during service start-up and then
+/// creates a `StructuredCounter` to emit
+/// instrumented data:
+///
+/// ```dart
+/// final recorder = obtainMetricRecorder();
+/// final counter = StructuredCounter(
+///   recorder: recorder,
+///   name: 'http_requests_total',
+///   description: 'Requests grouped by method.',
+/// );
+///
+/// counter.increment(attributes: {'method': 'GET'});
+/// counter.add(5, attributes: {'method': 'POST'});
+/// ```
+class StructuredCounter {
+  /// Creates a counter named [name] using the provided [recorder].
+  StructuredCounter({
+    required MetricRecorder recorder,
+    required String name,
+    String? description,
+  }) : _counter = recorder.counter(name, description: description);
+
+  final Counter _counter;
+
+  /// Increments the counter by 1 with optional [attributes].
+  void increment({Map<String, String>? attributes}) =>
+      _counter.add(1, attributes: attributes);
+
+  /// Adds an arbitrary [value] to the counter with optional [attributes].
+  void add(num value, {Map<String, String>? attributes}) =>
+      _counter.add(value, attributes: attributes);
+}

packages/observability/lib/src/histograms.dart

@@ -0,0 +1,36 @@
+import 'package:observability/src/metrics.dart';
+
+/// Lightweight wrapper that produces a [Histogram] from a [MetricRecorder] and
+/// offers ergonomic helpers for recording numeric values.
+///
+/// ```dart
+/// final recorder = obtainMetricRecorder();
+/// final latency = StructuredHistogram(
+///   recorder: recorder,
+///   name: 'worker_latency_ms',
+///   description: 'Latency grouped by route.',
+/// );
+///
+/// latency.record(42, attributes: {'route': '/hello'});
+/// latency.recordDuration(const Duration(milliseconds: 12));
+/// ```
+class StructuredHistogram {
+  /// Creates a histogram named [name] using the provided [recorder].
+  StructuredHistogram({
+    required MetricRecorder recorder,
+    required String name,
+    String? description,
+  }) : _histogram = recorder.histogram(name, description: description);
+
+  final Histogram _histogram;
+
+  /// Records a numeric [value] with optional dimension attributes.
+  void record(num value, {Map<String, String>? attributes}) {
+    _histogram.record(value, attributes: attributes);
+  }
+
+  /// Records the provided [duration] expressed in milliseconds.
+  void recordDuration(Duration duration, {Map<String, String>? attributes}) {
+    record(duration.inMilliseconds, attributes: attributes);
+  }
+}