talaria_serverpod

Serverpod 4 adapter for Talaria. Same ingest contract as talaria: exceptions plus optional APM spans for endpoints, Postgres, and FutureCalls.

This package re-exports the core API. Add both talaria and talaria_serverpod to the server pubspec.

Docs: Serverpod guide · Dart core · Flutter

Tracing and analytics follow project configuration.

Install

dependencies:
  talaria: ^0.3.7
  talaria_serverpod: ^0.2.4
  serverpod: ^4.0.0

Create a client key under Project settings → Client keys (tal_live_…). Default keys include eventsWrite and spansWrite. The API key decides the environment.

Wire it

Pass databaseInterceptor to the Serverpod constructor — Serverpod does not allow swapping it later. interceptDatabase no-ops until TalariaServerpod.init and until tracing is on.

import 'package:serverpod/serverpod.dart';
import 'package:talaria_serverpod/talaria_serverpod.dart';

void run(List<String> args) async {
  final pod = Serverpod(
    args,
    Protocol(),
    Endpoints(),
    databaseInterceptor: TalariaServerpod.interceptDatabase,
    experimentalFeatures: ExperimentalFeatures(
      diagnosticEventHandlers: [
        AsEventHandler<ExceptionEvent>((event, {required space, required context}) {
          TalariaServerpod.handleExceptionEvent(event);
        }),
      ],
    ),
  );

  await TalariaServerpod.init(TalariaOptions(
    dsn: 'https://ingest.newtalaria.com',
    apiKey: 'tal_live_…',
    release: '1.2.3',
    minLevel: SeverityLevel.warning,
    // tracing follows the project policy document
    tags: {'service': 'my_api'},
  ));

  TalariaServerpod.attach(pod);
  await pod.start();
}

On shutdown: await Talaria.flush(); await Talaria.close();.

What is instrumented

Surface	Span
Endpoint RPC + web routes	SERVER {METHOD} {route} — continues inbound W3C traceparent
Postgres / SQLite ORM and unsafeQuery	CLIENT db.system.name, sanitized SQL when available
FutureCalls	CONSUMER FutureCall.{name} (never adopted from another session)
Streaming methods	SERVER for the stream lifetime (not per chunk)
Uncaught diagnostics	One event per throw, isolated per session
Authenticated session	enduser.id / user.id on the session span
Outbound HTTP	HttpClient after init continues the active trace. package:http still uses Talaria.wrapHttpClient

Skipped: ingest (ingest and ingestBatch), Insights, /livez, /readyz, /startupz, /robots.txt, /favicon.ico, and /.well-known/.

ORM spans send a db.query.text stand-in (SELECT Product) when raw SQL is unavailable. Bind values are never sent. Repeated identical queries are each sent so N+1 stays visible.

Outbound HTTP

dart:io HttpClient created after TalariaServerpod.init sends traceparent and records a client span while a request span is open. Ingest URLs are skipped. For package:http:

final httpClient = Talaria.wrapHttpClient(http.Client());

Never wrap the SDK ingest client. Redis and other caches are opt-in — wrap them with Talaria.startSpan.

Manual spans

final span = Talaria.startSpan('charge', kind: SpanKind.client);
try {
  await charge();
  span.setStatus(SpanStatus.ok);
} catch (e, st) {
  span.markError(message: e.toString());
  await Talaria.captureException(e, stackTrace: st);
  rethrow;
} finally {
  span.finish();
}

See the talaria README for logger levels, sampling, breadcrumbs, and getTraceparent().

Dashboard

Spans use the same wire as the other official SDKs. The customer Performance UI (waterfall, dependencies, slow queries, RED) shows them.

License

MIT