Talaria

Docs / SDKs / PHP

PHP SDK

Composer package newtalaria/logging — PSR-3 logging, batched ingest, and optional tracing.

Building on Silverstripe CMS? Use the Silverstripe framework guide — same Composer package, with Monolog and browser wiring. Full reference: Packagist README.

PHPSilverstripeAll platforms

Install

bash
composer require newtalaria/logging

Initialize

Use a project client key (tal_live_…). In production set minLevel: 'warning' and put stable product dimensions in init tags.

php
use Talaria\Talaria;

Talaria::init([
    'dsn' => getenv('TALARIA_DSN') ?: 'https://api.newtalaria.com',
    'apiKey' => getenv('TALARIA_API_KEY'),
    'environment' => getenv('TALARIA_ENVIRONMENT') ?: 'production',
    'release' => getenv('TALARIA_RELEASE') ?: null,
    'minLevel' => 'warning', // production: drop info/debug noise
    'tags' => ['service' => 'api', 'platform' => 'php'],
    'maxBatchSize' => 50,
    'flushIntervalMs' => 2000,
]);

Logger API

Prefer Talaria::logger (or withTags) and level methods. Exceptions stay on captureException. Gates run minLevel → sampleRate → beforeSend. Talaria\\Logger also implements PSR-3.

php
$logger = Talaria::logger([
    'tags' => ['feature' => 'checkout', 'operation' => 'pay'],
]);

$logger->info('Checkout opened', ['extra' => ['cart_id' => '123']]);
$logger->warn('Payment method missing');

try {
    charge();
} catch (Throwable $e) {
    $logger->captureException($e, [
        'tags' => ['component' => 'stripe'],
    ]);
    throw $e;
}

// Child scopes inherit tags; minLevel can only raise the floor.
$payments = $logger->child([
    'tags' => ['component' => 'payments'],
    'minLevel' => 'error',
]);
$payments->error('Charge failed');

Tags and patterns

Use tags for low-cardinality filters; put ids and payloads in extra. On PSR-3 calls, pass throwables under exception so Talaria captures a real stack.

php
// tags = low-cardinality filters; extra = high-cardinality diagnostics
$logger->error('Charge declined', [
    'tags' => ['feature' => 'checkout', 'operation' => 'charge', 'component' => 'stripe'],
    'extra' => ['cart_id' => 'cart_01H…', 'decline_code' => 'insufficient_funds'],
]);

// PSR-3 still works — prefer exception key for stacks
$logger->error('Checkout failed', [
    'exception' => $e,
    'tags' => ['feature' => 'checkout'],
    'order_id' => '123',
]);

Silverstripe / Monolog

On Silverstripe, prefer the Injector LoggerInterface (handler default minLevel: warning). The same floor applies to the shared client for direct Talaria::* calls. Full module guide: Silverstripe SDK. Runnable demos: talaria-silverstripe-harness.

php
// Prefer Injector LoggerInterface on Silverstripe (Monolog handler, minLevel: warning)
use Psr\Log\LoggerInterface;

public function __construct(private LoggerInterface $logger) {}

public function pay(): void
{
    $this->logger->warning('Payment method missing', [
        'tags' => ['feature' => 'checkout'],
    ]);
}

Performance tracing

Tracing is off until enableTracing is true or tracesSampleRate is greater than 0. Head-based sampling: 100% of error transactions; default 10% of successful requests. The SDK instruments incoming HTTP, PDO/ORM queries, and outbound HTTP as child spans. Inspect waterfalls and RED in Performance. Child spans are not billed — only sampled root transactions. Framework-agnostic helpers: TracingPdo, RedisInstrumentation::wrap(), Psr15Middleware, and Talaria::getTraceparent() so outbound Guzzle can continue a browser traceparentfrom @newtalaria/browser.

php
Talaria::init([
    'dsn' => getenv('TALARIA_DSN') ?: 'https://api.newtalaria.com',
    'apiKey' => getenv('TALARIA_API_KEY'),
    'environment' => getenv('TALARIA_ENVIRONMENT') ?: 'production',
    'enableTracing' => true,
    'tracesSampleRate' => 0.1, // 10% of successful requests; errors always traced
]);

Already running an OpenTelemetry Collector? That is an advanced path — export OTLP/HTTP JSON to POST /otlp/v1/traces. Prefer the native SDK unless you already operate a Collector. See the API overview.

Troubleshooting

  • 401/403 — check API key and that it belongs to the target project.
  • No issue appears — confirm environment filter in the dashboard.
  • Rejected events — validate JSON shape against the API overview.
  • info missing — check minLevel (production and Silverstripe often use warning).
  • Exceptions dropped after setMinLevel('fatal') — captureException counts as error.

Prefer another language? See all SDKs or send events over HTTP via the API overview.

API overviewAll platformsQuickstart