Complete setup guide

End-to-end guide: account → SDK → production patterns → dashboard → alerts. Use this as the single walkthrough for new projects.

Overview

Step	What you do	Time
1	Create account & project	2 min
2	Configure environment variables	2 min
3	Install & wire SDK	5–15 min
4	Track APIs, LLMs, payments	10–30 min
5	Verify ingest & dashboard	2 min
6	Configure alerts & team	5 min

---

Step 1 — Account and project

1. Sign up: app.amlexia.com/signup
2. Create an organization (maps to Clerk org)
3. Create a project (e.g. production-api)
4. Open Settings → copy SDK key (am_...)
5. Store the key in your secrets manager — never commit it

Staging vs production

Pattern	When to use
Two projects	Separate SDK keys; safest for alerts
One project + AMLEXIA_ENVIRONMENT	Filter production / staging in dashboard

Details: Create a project

---

Step 2 — Environment variables

Add to server env (.env locally, secrets in production):

# Required
AMLEXIA_SDK_KEY=am_your_key_here

# Recommended
AMLEXIA_INGEST_URL=https://ingest.amlexia.com
AMLEXIA_ENVIRONMENT=production
AMLEXIA_RELEASE=1.2.3
AMLEXIA_SERVICE_NAME=api

Variable	Required	Purpose
AMLEXIA_SDK_KEY	Yes	Ingest authentication
AMLEXIA_INGEST_URL	No	Default https://ingest.amlexia.com; use http://localhost:8787 for local workers
AMLEXIA_ENVIRONMENT	No	Tags events; powers dashboard env filter & compare
AMLEXIA_RELEASE	No	Deploy version on each event
AMLEXIA_SERVICE_NAME	No	Service label (Django default: api)

Full reference: Environment variables

Never in the browser

Do not use NEXT_PUBLIC_AMLEXIA_*, client bundles, or mobile apps for the SDK key.

---

Step 3 — Install your SDK

Node.js

npm install @amlexiahq/node

Python

pip install amlexia
# Framework extras:
pip install "amlexia[fastapi]"

Go

go get github.com/amlexiahq/amlexia-go

Ruby

gem install amlexia

Package reference: SDK feature parity

---

Step 4 — Wire the client

Node.js (any framework)

import { AmlexiaClient, wrapFetch } from '@amlexiahq/node';

const client = AmlexiaClient.fromEnv();

// Optional: auto-track all outbound fetch (OpenAI, Stripe, etc.)
globalThis.fetch = wrapFetch(client, fetch);

process.on('SIGTERM', async () => {
  await client.shutdown();
  process.exit(0);
});

Python

from amlexia import AmlexiaClient
import atexit

client = AmlexiaClient.from_env()
atexit.register(client.shutdown)

Go

client, err := amlexia.NewFromEnv()
if err != nil { log.Fatal(err) }
defer client.Shutdown()

Ruby

client = Amlexia::Client.from_env
at_exit { client.shutdown }

Framework middleware (inbound HTTP)

Framework	Guide
Express	Express
Fastify	Fastify
Hono	Hono
Next.js App Router	Next.js
FastAPI	FastAPI
Flask	Flask
Django	Django
Bun / Deno / Workers	Bun, Deno & Edge

---

Step 5 — Track what matters

5a. Inbound API routes

Preferred: framework middleware (auto path normalization, trace headers).

Manual (cron, workers, scripts):

await client.track({
  endpoint: 'cron/sync-inventory',
  method: 'JOB',
  statusCode: 200,
  latencyMs: 4521,
  environment: process.env.AMLEXIA_ENVIRONMENT,
});

5b. OpenAI / Anthropic

Use helpers or manual track with tokens — ingest estimates cost when costUsd is omitted.

import { trackOpenAiCompletion } from '@amlexiahq/node';

await trackOpenAiCompletion(client, {
  model: response.model,
  statusCode: 200,
  latencyMs: Date.now() - start,
  usage: response.usage, // prompt_tokens, completion_tokens
});

Full guide: LLM tracking

5c. Stripe / payments

await client.track({
  endpoint: 'POST /v1/payment_intents',
  method: 'POST',
  statusCode: 200,
  latencyMs,
  provider: 'stripe',
  costUsd: amountUsd,
  metadata: { payment_intent_id: pi.id },
});

5d. Inbound webhooks

await client.track({
  endpoint: 'POST /webhooks/stripe',
  method: 'POST',
  statusCode: 200,
  latencyMs,
  provider: 'stripe',
  isWebhook: true,
});

5e. Distributed tracing

import { createTraceContext, childSpan, applyTraceToEvent } from '@amlexiahq/node/tracing';

const root = createTraceContext({ environment: 'production' });
const child = childSpan(root);
await client.track(applyTraceToEvent({
  endpoint: 'POST /internal/job',
  method: 'POST',
  statusCode: 200,
  latencyMs: 100,
}, child));

Full guide: Tracing

5f. HTTP outbound wrapper

HTTP wrappers — wrapFetch, Python wrap_requests_session, Go/Ruby equivalents.

5g. OpenTelemetry

Existing OTEL pipeline → OpenTelemetry

---

Step 6 — Client options (all SDKs)

Option	Default	Use
flushIntervalMs / flush interval	5s	Background upload
maxBatchSize	50	Events per POST
maxRetries	5	On network/5xx
sampleRate	1	0.5 = send ~50% of events
diagnostic	false	Log flush errors to stderr

Details: Sampling & diagnostics

---

Step 7 — Verify integration

Health CLI

npx amlexia health          # Node
amlexia health              # Python
go run .../cmd/amlexia health   # Go
amlexia health              # Ruby

Raw curl

curl -s -X POST https://ingest.amlexia.com/v1/events \
  -H "Content-Type: application/json" \
  -d "{\"sdk_key\":\"am_YOUR_KEY\",\"events\":[{\"endpoint\":\"GET /health\",\"method\":\"GET\",\"status_code\":200,\"latency_ms\":1,\"timestamp\":$(date +%s),\"environment\":\"production\"}]}"

Expect accepted / queued response.

Dashboard

1. app.amlexia.com → your project
2. Live — events within seconds
3. Overview — aggregates within ~1 minute
4. Providers — after outbound LLM/payment traffic
5. Sidebar usage meter — confirms billing month count

Troubleshooting: Troubleshooting

---

Step 8 — Use the dashboard

Page	Purpose
Overview	Traffic, latency, errors, cost (reported vs estimated)
Live	Real-time SSE stream
Traces	Distributed traces
Providers	Per-vendor health & model table
Operations	SLO, forecast, incidents
Insights	Recommendations + AI summary
Alerts	Rules & history
Settings	SDK key, retention, team

Full walkthrough: Using the dashboard

Global filters

• Time range: 1h / 24h / 7d / 30d
• Environment: filter by AMLEXIA_ENVIRONMENT
• Compare: side-by-side two environments
• Saved views: save filter presets

---

Step 9 — Alerts

1. Alerts → Create alert
2. Pick condition (latency, error_rate, cost, anomaly, …)
3. Channel: email, Slack, or HTTP webhook
4. Set threshold and severity

Guide: Alerts

---

Step 10 — Team & plans

• Team: Settings → invite via Clerk, assign roles — Team & RBAC
• Limits: Startup 10k events/month — Plans & limits

---

Step 11 — Production checklist

• [ ] AMLEXIA_SDK_KEY only in server secrets
• [ ] AMLEXIA_ENVIRONMENT set per deploy
• [ ] shutdown() / flush() on serverless
• [ ] Middleware on all HTTP servers
• [ ] LLM calls include model + tokens (or explicit costUsd)
• [ ] Stripe/webhooks tracked with provider + isWebhook
• [ ] npx amlexia health passes in CI or post-deploy
• [ ] Error-rate alert on critical routes
• [ ] Staging project or staging environment tag

Best practices

---

Local development

Run the monorepo workers and point ingest locally:

AMLEXIA_INGEST_URL=http://localhost:8787

Guide: Local development

---

AI-assisted setup

Paste a prompt into Cursor/Copilot: AI setup prompts

---

Next

• Cost & usage
• Event fields
• Dashboard API
• FAQ