Add diagnostic events

Diagnostic events are trail markers for investigations. Use them for meaningful application milestones such as checkout_submitted, payment_failed, or agent_step_completed.

They are not automatic clickstream capture and are not intended for growth analytics.

Use a project-scoped key with analytics:write. Add ingest:write only when the same SDK also sends traces, logs, metrics, or errors.

Capture an event

JavaScript / TypeScript

import { AnalyticsClient } from '@teml/sdk/analytics';

const events = new AnalyticsClient({
  endpoint: 'https://api.teml.io',
  apiKey: process.env.TEML_API_KEY!,
});

events.capture('checkout_submitted', {
  cart_size: 3,
  payment_provider: 'stripe',
});

Python

import os
import teml

events = teml.AnalyticsClient(
    endpoint='https://api.teml.io',
    api_key=os.environ['TEML_API_KEY'],
)
events.capture('checkout_submitted', {
    'cart_size': 3,
    'payment_provider': 'stripe',
}, distinct_id='user_8842')

Go

events := teml.NewAnalytics(teml.AnalyticsConfig{
	Endpoint: "https://api.teml.io",
	APIKey:   os.Getenv("TEML_API_KEY"),
})
defer events.Stop(ctx)

err := events.Capture(ctx, "checkout_submitted", map[string]any{
	"cart_size":        3,
	"payment_provider": "stripe",
}, teml.WithDistinctID("user_8842"))

Swift (iOS)

Teml.capture("checkout_submitted", properties: [
    "cart_size": 3,
    "payment_provider": "stripe",
])

Kotlin (Android)

Teml.capture(
    "checkout_submitted",
    mapOf("cart_size" to 3, "payment_provider" to "stripe"),
)

React Native

await Teml.capture('checkout_submitted', {
  cart_size: 3,
  payment_provider: 'stripe',
});

Flutter

await Teml.capture('checkout_submitted', properties: {
  'cart_size': 3,
  'payment_provider': 'stripe',
});

Stop the event client during graceful shutdown so buffered events can finish sending. In JavaScript, the event client shares the active identity and browser session with the main SDK. Python and Go can use the shared identity or an explicit request-scoped ID as shown above. Do not create a second customer ID field inside event properties.

Choose useful events

Record events that help an engineer answer a production question:

• a workflow entered a meaningful state;
• a rollout or provider choice changed behavior;
• a customer-visible operation succeeded or failed; or
• an agent or background job completed a significant step.

Avoid high-volume noise such as every mouse movement, DOM mutation, or internal function call.

Verify

Open Events, select the event, and pivot to a customer who triggered it. The event should also appear in that customer’s timeline alongside surrounding errors, traces, and replay.

• Identify customers
• Inspect events and customer cohorts