talaria 0.2.0

Official Dart SDK for Talaria — capture exceptions and logs into triageable issues.

talaria

Official Dart SDK for Talaria — capture exceptions and application logs into triageable issues.

Events are queued in memory and sent with batch ingest when the buffer hits a size limit, exceeds a max age, or you call flush / close. Fingerprinting stays on the server.

Docs: Dart SDK guide · Flutter: talaria_flutter · Serverpod: talaria_serverpod · Dashboard: one.newtalaria.com

Install

dependencies:
  talaria: ^0.2.0

Initialize

Create a client key under Project settings → Client keys (tal_live_…).

import 'package:talaria/talaria.dart';

await Talaria.init(TalariaOptions(
  dsn: 'https://api.newtalaria.com',
  apiKey: 'tal_live_…',
  environment: 'production', // staging | development also accepted
  release: '1.4.2',
  commitSha: const String.fromEnvironment('TALARIA_COMMIT_SHA'),
  minLevel: SeverityLevel.warning,
  sampleRate: 1.0,
  tags: {
    'service': 'api',
    'platform': 'dart',
  },
));

Prefer runZonedTalaria (or talaria_flutter) so uncaught errors are captured:

final client = await Talaria.init(/* … */);
runZonedTalaria(client, () {
  // your app entry
});

Logging

final logger = Talaria.logger(tags: {
  'feature': 'checkout',
  'operation': 'pay',
});

await logger.info('Checkout opened'); // filtered if minLevel is warning
await logger.warn('Payment method missing');

try {
  await charge();
} catch (e, st) {
  await logger.captureException(e, stackTrace: st, context: CaptureContext(
    tags: {'component': 'stripe'},
    extra: {'cart_id': 'abc123'},
  ));
  rethrow;
}

Method	Severity sent
debug / info / warning / error / fatal	same name
warn	warning
log(level, message)	mapped severity
captureException	error

Filtering

Gates run in order. Filtered calls are quiet no-ops.

1. minLevel — default/root severity
2. sampleRate — fraction of eligible events to enqueue
3. beforeSend — return null to drop, or a mutated event

Scoped loggers may override below the root unless enforceDefaultLevel is true. Full rules: logging-levels.md.

Tracing (APM)

Tracing is off until you set enableTracing: true or tracesSampleRate > 0. Successful transactions default to a 10% sample; error transactions are always sent.

await Talaria.init(TalariaOptions(
  dsn: 'https://api.newtalaria.com',
  apiKey: 'tal_live_…',
  environment: 'production',
  enableTracing: true, // 10% of successful transactions
  // tracesSampleRate: 0.25, // also enables tracing
));

final txn = Talaria.startTransaction('checkout');
try {
  final child = Talaria.startSpan('charge', kind: SpanKind.client);
  // …
  child.finish();
} catch (e, st) {
  txn.markError(message: e.toString());
  await Talaria.captureException(e, stackTrace: st);
  rethrow;
} finally {
  txn.finish();
}

Spans POST to /spans/ingestBatch (IngestSpanBatchInput). Events stay on /events/ingestBatch.

Outbound HTTP

Wrap application package:http clients. Never wrap the ingest client used by HttpTransport (or pass a separate spanHttpClient for span POSTs).

final httpClient = Talaria.wrapHttpClient(http.Client());
final response = await httpClient.get(Uri.parse('https://api.partner.dev/v1/pay'));

This starts a client span, injects W3C traceparent, and records an HTTP breadcrumb. Talaria ingest URLs are skipped if wrapped by mistake. Talaria.getTraceparent() returns the active header when a span is recording.

For Serverpod 4 apps, use talaria_serverpod (TalariaServerpod.attach + databaseInterceptor) instead of starting transactions by hand. SQL helpers (SqlSanitizer, DbSpan) and concurrent SpanScope live in this core package.

There is no talaria_dio package. For Dio, wrap the adapter's http.Client with TalariaHttpClient, or add an interceptor that calls Talaria.startSpan / injects traceparent. Use addProcessor for per-request url / requestId / tags on a shared client:

Talaria.addProcessor((bag) {
  return {
    ...bag,
    'url': currentRequestUrl,
    'requestId': currentRequestId,
  };
});

Breadcrumbs

A ring buffer of 50 breadcrumbs is attached on error events, with traceId / spanId when a span is in scope.

Talaria.addBreadcrumb(Breadcrumb(
  type: 'user',
  category: 'ui',
  message: 'Tapped Pay',
));

Shutdown

await Talaria.flush();
await Talaria.close();

Notes

• Events: POST /events/ingestBatch with X-API-Key
• Spans: POST /spans/ingestBatch when tracing is enabled
• Never computes fingerprints
• Main-isolate only in v1 — use Flutter package for framework hooks