Browse documentation

Start here

Quickstart: see your first customer story

Connect one application, identify a test customer, and follow an error across their Teml timeline.

This quickstart proves the part of Teml that matters: signals from one application become one connected story for the customer they affected.

You will send a trace and a test error, attach both to a customer, and inspect the result in the dashboard. Allow about ten minutes.

Before you start

You need:

  • access to a Teml organization;
  • a project in Settings → Projects; and
  • a project-scoped API key with ingest:write and analytics:write in Settings → Access.

This example needs both scopes: traces and errors use ingest:write, while Identify uses the diagnostic capture surface protected by analytics:write. Choose Custom access when creating the key; the Ingest only preset contains only ingest:write.

Keep the API key in an environment variable. Do not put it in source code.

export TEML_API_KEY="tm_..."

1. Install an SDK

Choose the language used by your service. JavaScript and Python commands use the registry packages after their release; during early access, use the artifact or source install described in the language guide.

JavaScript / TypeScript

mkdir teml-quickstart && cd teml-quickstart
npm init -y
npm install @teml/sdk

Python

mkdir teml-quickstart && cd teml-quickstart
python -m venv .venv
source .venv/bin/activate
pip install teml

Go

mkdir teml-quickstart && cd teml-quickstart
go mod init example.com/teml-quickstart
go get github.com/getteml/teml/sdks/go@main

Using a browser or mobile stack? Start with Choose an integration.

2. Start Teml and identify a customer

JavaScript / TypeScript

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

const apiKey = process.env.TEML_API_KEY;
if (!apiKey) throw new Error('TEML_API_KEY is required');

const teml = await init({
  apiKey,
  serviceName: 'quickstart',
  environment: 'development',
});
const events = new AnalyticsClient({
  endpoint: 'https://api.teml.io',
  apiKey,
});

events.identify('quickstart-user', {
  email: 'quickstart@example.com',
  plan: 'test',
});

const span = teml.startSpan('checkout');
teml.captureError(new Error('quickstart payment failure'));
span.end();

await events.stop();
await teml.stop();

Save this as quickstart.mjs.

Python

import os
import teml

with teml.TemlClient(
    api_key=os.environ['TEML_API_KEY'],
    service_name='quickstart',
    environment='development',
) as client:
    client.identify('quickstart-user', {
        'email': 'quickstart@example.com',
        'plan': 'test',
    })
    with client.start_span('checkout'):
        client.capture_error(RuntimeError('quickstart payment failure'))

Save this as quickstart.py.

Go

package main

import (
	"context"
	"errors"
	"os"

	teml "github.com/getteml/teml/sdks/go"
)

func main() {
	ctx := context.Background()
	client, err := teml.New(
		teml.WithAPIKey(os.Getenv("TEML_API_KEY")),
		teml.WithServiceName("quickstart"),
		teml.WithEnvironment("development"),
	)
	if err != nil {
		panic(err)
	}

	if err := client.Start(ctx); err != nil {
		panic(err)
	}
	defer client.Stop(ctx)

	if err := client.Identify(ctx, "quickstart-user", map[string]any{
		"email": "quickstart@example.com",
		"plan":  "test",
	}); err != nil {
		panic(err)
	}

	traceCtx, span := client.StartSpan(ctx, "checkout")
	client.CaptureError(traceCtx, errors.New("quickstart payment failure"))
	span.End()
}

Save this as main.go.

Run the program once:

JavaScript / TypeScript

node quickstart.mjs

Python

python quickstart.py

Go

go run .

3. Open the customer story

In Teml:

  1. Select the same project and the development environment.
  2. Open Customers.
  3. Search for quickstart@example.com or quickstart-user.
  4. Open the customer.

The activity timeline should contain the error and trace you just sent. Open the error to see its Issue, then return to the customer to keep the investigation anchored to the person.

4. Ask Teml what happened

Select Explain this person on the customer page, or open Investigate and ask:

What happened to quickstart@example.com?

Teml gathers matching evidence and links each claim back to the underlying signal.

If nothing appears

Most setup failures are an API key, project, environment, or shutdown/flush mismatch. Follow No data is appearing before changing sampling or transport settings.

Next