Skip to content

API_REFERENCE.md

Latest commit

 

History

History
137 lines (102 loc) · 6.99 KB

API_REFERENCE.md

File metadata and controls

137 lines (102 loc) · 6.99 KB
Raw

API Reference

TelemetryFlow\Core\* namespace — the framework-agnostic core.

Static Factories — TelemetryFlow\Core\TelemetryFlow

Method Description
TelemetryFlow::newFromEnv(): Client Build a client from TELEMETRYFLOW_* env vars.
TelemetryFlow::newSimple(string $keyId, string $keySecret, string $endpoint, string $serviceName): Client Minimal explicit configuration.
TelemetryFlow::builder(): Builder Returns a fluent Builder.

Builder — TelemetryFlow\Core\Builder

All with*() methods return $this for chaining. Call build() to create the Client.

Identity & Transport

Method Env var
withApiKey(string $id, string $secret) TELEMETRYFLOW_API_KEY_ID / _SECRET
withApiKeyFromEnv() as above
withEndpoint(string $endpoint) TELEMETRYFLOW_ENDPOINT
withService(string $name, string $version = '1.0.0') TELEMETRYFLOW_SERVICE_NAME
withProtocol(Protocol $protocol) / withGrpc() / withHttp() TELEMETRYFLOW_PROTOCOL
withInsecure(bool $insecure = true) TELEMETRYFLOW_INSECURE
withTimeoutSeconds(float $seconds) TELEMETRYFLOW_TIMEOUT
withCompression(bool $enabled) TELEMETRYFLOW_COMPRESSION

Signals

Method Description
withSignals(bool $metrics, bool $logs, bool $traces) Toggle each signal.
withMetricsOnly() / withLogsOnly() / withTracesOnly() Convenience presets.
withExemplars(bool $enabled) Metrics-to-traces exemplars.

TFO v2 API

Method Description
withV2Api(bool $enabled) Use /v2/* endpoints (default on).
withV2Only() Reject v1 endpoints.
withTracesEndpoint(string $path) Custom traces path.
withMetricsEndpoint(string $path) Custom metrics path.
withLogsEndpoint(string $path) Custom logs path.

Collector Identity

Method Env var
withCollectorID(string $id) TELEMETRYFLOW_COLLECTOR_ID
withCollectorName(string $name) TELEMETRYFLOW_COLLECTOR_NAME
withCollectorHostname(string $host) TELEMETRYFLOW_COLLECTOR_HOSTNAME
withCollectorTag(string $key, string $value) —
withCollectorTags(array $tags) —
withEnrichResources(bool $enabled) TELEMETRYFLOW_ENRICH_RESOURCES
withDatacenter(string $dc) TELEMETRYFLOW_DATACENTER
withServiceNamespace(string $ns) TELEMETRYFLOW_SERVICE_NAMESPACE
withCustomAttribute(string $key, string $value) —
withAutoConfiguration() Pulls all standard env vars at once.

build(): Client — validates and returns the client (throws RuntimeException on missing required values).

Client — TelemetryFlow\Core\Client

Lifecycle

Method Description
initialize(): void Create exporters, register providers.
shutdown(float $timeoutSeconds = 30.0): void Flush + release resources.
flush(float $timeoutSeconds = 10.0): void Force flush without shutdown.
isInitialized(): bool Current state.
config(): TelemetryConfig The resolved configuration.

Metrics

incrementCounter(string $name, int $value = 1, array $attributes = []): void
recordGauge(string $name, float $value, array $attributes = []): void
recordHistogram(string $name, float $value, string $unit = '', array $attributes = []): void
recordMetric(string $name, float $value, string $unit = '', array $attributes = []): void

Logs

log(string $severity, string $message, array $attributes = []): void
logInfo(string $message, array $attributes = []): void
logWarn(string $message, array $attributes = []): void
logError(string $message, array $attributes = []): void
logDebug(string $message, array $attributes = []): void

Traces

startSpan(string $name, string $kind = 'internal', array $attributes = []): string
endSpan(string $spanId, ?\Throwable $error = null): void
addSpanEvent(string $spanId, string $name, array $attributes = []): void

$kind is one of: internal, server, client, producer, consumer.

Instrumentation

PSR-15 — TelemetryFlow\Core\Instrumentation\Http\HttpMiddleware

new HttpMiddleware(new InstrumentationConfig(serviceName: 'my-app'))

Records http.server.request.{count,duration,body.size,response.body.size} and an HTTP server span.

Guzzle — TelemetryFlow\Core\Instrumentation\Http\GuzzleMiddleware

$stack = HandlerStack::create();
$stack->push(GuzzleMiddleware::factory($config));
new Client(['handler' => $stack]);

Injects W3C trace context and creates a client span per request.

Laravel Facade

The TelemetryFlow facade proxies every Client method plus isInitialized() and client().

Generator CLI

telemetryflow-gen init        # scaffold telemetry/init.php + .env.telemetryflow
telemetryflow-gen example     # generate basic / http-server example
telemetryflow-gen config      # generate .env.telemetryflow only
telemetryflow-gen version     # version info