Getting Started Checklist for Distlang Users · 2026
Why You Need a Getting Started Checklist for Distlang Users
Onboarding to any new developer tool means absorbing a pile of unfamiliar terminology in a short window. Distlang is no different. You’ll encounter concepts from three different domains all at once: authentication, metrics theory, and serverless runtime quirks. Miss one and you might spend an hour debugging silent data loss that a two-sentence definition could have prevented.
This glossary is structured as a checklist. It follows the exact sequence you’ll move through during setup: create an account, understand your metrics primitives, handle serverless lifecycle patterns, then get familiar with the tooling. Each term gets a plain definition, a note on what it means specifically in Distlang, and a warning about the common mistake associated with it.
Ready to follow along with a live account? Sign up at dash.distlang.com and keep this page open in a second tab.
Account and Authentication Terms
These are the first concepts you’ll hit after signing up. Get these right and the rest of onboarding is smooth.
API Token (Distlang)
A single long-lived token that authenticates every metrics request your application sends. Distlang uses one API token per account, which is a deliberate simplification. Larger platforms often require you to manage multiple API keys, service accounts, and scoped tokens. Distlang trades that granularity for speed: you copy one token, paste it into your environment, and you’re done.
Why it matters: Without a valid API token, no metric data reaches Distlang. It’s the first thing you need after creating your account. Learn how to generate yours in the API tokens documentation.
Common mistake: Committing your token to a public Git repository. Use environment variables instead.
Bearer Token Auth
The HTTP authentication scheme Distlang uses. You pass your API token in the Authorization header as Authorization: Bearer <token>. Bearer tokens grant access to whoever holds them, which is why HTTPS is non-negotiable. Never send a bearer token over plaintext HTTP. Over 70% of modern APIs use bearer tokens for access control, so this pattern will feel familiar if you’ve worked with Stripe, GitHub, or similar APIs.
Why it matters: Every single metrics write to the Distlang Metrics API uses this header. If you forget it or format it wrong, you’ll get authentication errors with zero data flowing.
Hosted Dashboard (dash.distlang.com)
Distlang auto-generates a dashboard for every metric set you create. No Grafana setup. No Prometheus configuration. No YAML files describing panel layouts. You instrument your code, send data, and a dashboard appears.
Why it matters: This is where you verify that your instrumentation is working. During onboarding, dash.distlang.com is your feedback loop. If data shows up here, your setup is correct.
Core Metrics Concepts
This section covers the building blocks of any metrics system. Serverless observability practitioners consistently recommend the same approach: start small with basic instrumentation, focus on the metrics that matter most, and expand coverage gradually. Distlang follows this philosophy by giving you just two metric types to start with.
Counter
A metric that only goes up. Counters track cumulative events: HTTP requests served, errors thrown, jobs processed, database queries executed. They never decrease (except when your process restarts, which resets them to zero).
In Distlang, you record counter values through the JS client’s counter methods on a metric set. Think of a counter as answering the question “how many times did X happen?”
Why it matters: Counters are your first line of visibility. If you instrument nothing else, instrument a request counter and an error counter. For a hands-on walkthrough, see counters and histograms in practice.
Histogram
A metric that records the distribution of numeric observations by grouping them into buckets. Unlike an average, a histogram preserves the shape of your data, including tails, skew, and multimodal patterns that a single number hides.
In Distlang, histograms capture things like response latency or payload sizes. This is critical for understanding p95 and p99 behavior in serverless workloads, where the worst-case experience matters more than the average.
Why it matters: Counters tell you how often something happened. Histograms tell you how long or how big it was. Together, they cover most operational questions. As practitioners in the metrics community point out, counters, histograms, and other types are not interchangeable containers for “some number.” Each preserves a different shape of information, and your dashboards are only as good as the underlying type.
For a deeper comparison, read about instrumenting counters and histograms in JavaScript.
Metric Set
A Distlang-specific concept. A metric set is a named grouping of related metrics. It maps loosely to a “metric namespace” or “registry” in other systems (similar to how Dropwizard’s MetricRegistry class serves as the container for all your application’s metrics).
Why it matters: Distlang auto-generates one dashboard per metric set. The way you organize metric sets directly determines your dashboard layout. Name them intentionally.
Labels and Cardinality
Labels are key-value attributes attached to individual metric data points. For example: route="/api/users", method="GET", status="200". They let you filter and group data on your dashboard.
Cardinality is the number of unique label combinations. High cardinality (thousands of unique values) causes storage bloat and slow queries. A user ID as a label is high cardinality. An HTTP method is low cardinality.
Why it matters: New users often over-label their metrics and then wonder why queries are slow or their row quotas get consumed quickly. Keep label cardinality low.
Instrumentation
The act of adding measurement code to your application. In Distlang, this means importing @distlang/client, defining a metric set, and calling counter or histogram methods inside your request handlers.
Why it matters: If you haven’t instrumented anything, there’s nothing to see on your dashboard. Instrumentation is the single step that separates “signed up” from “getting value.” For a broader view, check the application instrumentation guide for Cloudflare and Vercel.
Rows (Ingestion Quota)
The billing unit in Distlang. Each metric data point you submit counts as one row. Plans range from 500K rows/month on the Free tier to 20M rows/month on Growth.
Why it matters: Understanding row volume prevents billing surprises. If you record 10 metrics per request and get 100K requests/month, that’s 1M rows. Plan accordingly.
Metric Retention
How long Distlang stores your data. Retention is 7 days on Free and Launch, 14 days on Hobby, and 30 days on Growth.
Why it matters: If you need to analyze trends over months, you’ll need to export data or choose an appropriate plan. Don’t instrument long-term trend analysis against a 7-day retention window without a plan for persistence.
You can compare plan features to find the right fit for your project.
Serverless Lifecycle Patterns
This is where the getting started checklist for Distlang users gets specific to serverless runtimes. The stateless, short-lived nature of serverless functions creates real challenges for observability. Functions can terminate before asynchronous work completes, which means your metrics might never arrive. Every term in this section exists because of that constraint.
Flush and Flush Semantics
Flushing is the process of sending buffered metric data from your application to the Distlang Metrics API. The JS client buffers metrics in memory and sends them in batches for efficiency.
In serverless environments, the runtime may kill your function before an asynchronous flush finishes. This is why Distlang’s client provides configurable flush behavior. For Cloudflare Workers specifically, practitioners recommend setting flushAt to 1 and flushInterval to 0 to avoid batching entirely, because batched data sent asynchronously can be lost when Workers terminate early.
Why it matters: Get flush configuration wrong and you lose data silently. No errors, no warnings, just missing metrics on your dashboard. Read the deep dive on flush configuration for the full picture.
ctx.waitUntil() (Cloudflare Workers)
A Cloudflare Workers API that extends the lifetime of your Worker invocation. It accepts a Promise that the runtime will continue executing even after a response has been returned to the client. Execution can continue for up to 30 seconds after the response is sent.
In Distlang’s Cloudflare Workers quickstart, you wrap your metrics flush call in ctx.waitUntil(). This lets you return a fast response to the user while ensuring metrics data actually gets transmitted.
Why it matters: Without ctx.waitUntil(), your flush becomes a floating promise (see below) and your metrics vanish. This is the most common mistake new Distlang users make on Cloudflare Workers. The Workers instrumentation guide walks through the exact pattern.
after() (Vercel/Next.js)
The Vercel equivalent of ctx.waitUntil(). In Next.js 15.1 and above, the after() function lets you schedule work that runs after the response is sent. For older versions, Vercel provides a waitUntil helper method.
Distlang provides a quickstart showing how to use after() for metrics flush in Vercel deployments.
Why it matters: If you’re deploying to Vercel instead of Cloudflare, this is the function you need. Same problem, different API. See the Vercel quickstart for the copy-paste example.
Floating Promise
A Promise that is not awaited, not returned, and not passed to ctx.waitUntil(). Floating promises are silent bugs. The Workers runtime may terminate your isolate before a floating promise resolves, which means dropped results, swallowed errors, and unfinished work.
In Distlang, a floating flush promise means your metrics data is silently lost. You won’t see an error. You’ll just see gaps on your dashboard and wonder what happened.
Why it matters: This is the number one cause of “I instrumented everything but my dashboard is empty.” Always pass your flush to ctx.waitUntil() or after().
Cold Start
When a serverless function is invoked after sitting idle, the runtime spins up a new execution environment from scratch. This adds latency to the first request. Cold starts are rare in aggregate but highly impactful at p99, which is exactly why histograms matter for measuring them.
Why it matters: Cold starts affect time-to-first-metric because the Distlang client must initialize during this window. Understanding cold start behavior helps you interpret early latency spikes in your dashboard data.
API-First and Serverless-Native
Distlang’s architecture sends metrics data directly from your application code via HTTP API calls. There are no agents to install, no sidecars to configure, no background daemons to keep running. This design is necessary in serverless and edge runtimes where you simply cannot run persistent processes.
As one serverless observability guide explains, the ephemeral, fine-grained nature of serverless functions makes it challenging to continuously monitor their behavior. Distlang’s API-first approach is a direct response to that challenge.
Distlang Tools and Features
Now that you understand the concepts, here are the specific tools that make up the Distlang developer experience.
@distlang/client (JS Client)
The lightweight JavaScript SDK for recording counters and histograms. It handles metric buffering, flush timing, and HTTP transport to the Metrics API. It’s designed specifically for edge and serverless runtimes where traditional monitoring agents cannot run.
Why it matters: This is the primary integration path for JavaScript developers. Import it, define a metric set, call counter and histogram methods, flush. Four steps to working metrics. See the full JS client reference for all available methods.
Metrics API (Distlang)
The raw HTTP endpoint for ingesting metric data. It accepts JSON payloads with bearer token auth. If you’re working in Python, Go, Ruby, or any non-JavaScript language, you can integrate by sending HTTP POST requests directly to this endpoint.
Why it matters: The JS client is a convenience wrapper around this API. But the API itself is language-agnostic, which means Distlang works with any stack that can make an HTTP request.
AI Chart Suggestions
A Distlang feature that automatically suggests chart titles and descriptions based on your incoming metric data. When your dashboard auto-generates, you don’t have to manually label every chart. The system infers reasonable names from the metric set and data patterns.
Why it matters: Dashboard setup friction is real. Naming charts is tedious. This feature gets you to a usable dashboard faster, especially during the “just exploring” phase of onboarding.
Distlang CLI
The command-line tool that compiles JavaScript worker applications, runs them locally, and packages them for deployment. It uses workerd (Cloudflare’s open-source runtime) under the hood for local development.
Why it matters: The CLI is your local development loop. Write code, test locally, deploy when ready. No cloud round-trips during development.
workerd
Cloudflare’s open-source JavaScript and WASM runtime. The Distlang CLI uses workerd to run your instrumented Workers locally, so you can verify metrics instrumentation before deploying to production.
Why it matters: Testing metrics locally means you catch instrumentation mistakes before they hit production, where debugging is harder and data loss matters more.
Helpers and Layers
Distlang’s model for composing reusable application capabilities. Instead of wiring infrastructure by hand, you import helpers (metrics, ObjectDB storage, etc.) directly into your code as modules. This is a key differentiator from standalone monitoring tools. For more context on how this model works, read about what helpers are in Distlang.
Why it matters: Helpers reduce the glue code between your application and its infrastructure dependencies. Metrics become an import, not a configuration project.
Hosted Deploy
One-command deployment via the Distlang CLI that returns a managed *.distlang.com subdomain. No DNS configuration, no cloud provider consoles, no infrastructure provisioning.
Why it matters: Perfect for demos, prototypes, and testing. You go from local code to a live URL in seconds.
Quick Checklist: Am I Ready?
Use this as a final self-assessment. If you can check every box, you’re ready to instrument your first application.
- [ ] I have a Distlang account and can access dash.distlang.com
- [ ] I’ve generated my API token and stored it in an environment variable
- [ ] I understand the difference between a counter and a histogram
- [ ] I know what a metric set is and how it maps to dashboards
- [ ] I can explain flush semantics and why they matter in serverless environments
- [ ] I know to use
ctx.waitUntil()on Cloudflare Workers orafter()on Vercel - [ ] I understand what a floating promise is and how to avoid creating one
- [ ] I’ve chosen my environment quickstart (Cloudflare or Vercel)
- [ ] I know my plan’s row quota and retention limits
If any box is unchecked, scroll back up to the relevant section. If they’re all checked, head to the metrics quickstart and start building.
For a complete end-to-end walkthrough, the app to dashboard tutorial takes you from zero to a working dashboard in minutes.
FAQ
What is a getting started checklist for Distlang users?
It’s a structured reference covering every concept and tool you encounter during Distlang onboarding. Rather than an alphabetical glossary, it’s organized by the order you’ll actually need each term, from account setup through your first dashboard. If you understand every term in this checklist, you’re ready to instrument your application.
Do I need to know Prometheus or Grafana before using Distlang?
No. Distlang is designed to work without traditional observability infrastructure. There are no agents to install, no time-series databases to configure, and no Grafana dashboards to build manually. Distlang auto-generates dashboards per metric set. If you’ve ever made an HTTP request with a bearer token, you have enough background.
What’s the difference between a counter and a histogram in Distlang?
A counter tracks how many times something happened (requests, errors, jobs). It only goes up. A histogram tracks the distribution of a measurement (latency, payload size) across buckets. Use counters for event counts, histograms for durations and sizes. The choice matters because dashboards and alerting depend on the underlying metric type preserving the right shape of information.
Why do my metrics disappear on Cloudflare Workers?
Almost certainly a floating promise. If you call the flush method without passing it to ctx.waitUntil(), the Workers runtime can terminate your isolate before the flush completes. The data never reaches Distlang and you see nothing on your dashboard. Always wrap your flush in ctx.waitUntil().
How many rows does my application need per month?
Multiply the number of metrics you record per request by your expected request volume. For example, 5 metrics per request at 200K requests/month equals 1M rows. The Free plan includes 500K rows/month, Launch includes 1.5M, Hobby includes 5M, and Growth includes 20M.
Can I use Distlang with languages other than JavaScript?
Yes. The Metrics API accepts standard HTTP POST requests with JSON payloads and bearer token authentication. Any language or runtime that can make HTTP requests can send metrics to Distlang. The JS client is a convenience wrapper, not a requirement.
What happens to my data after the retention period?
Data older than your plan’s retention window is no longer available on the dashboard. Retention is 7 days on Free and Launch, 14 days on Hobby, and 30 days on Growth. If you need longer-term analysis, plan for data export or choose a tier with longer retention.
How does Distlang compare to Datadog or New Relic for serverless?
Distlang is purpose-built for serverless and edge runtimes where agents cannot run. It’s API-first, requires no infrastructure setup, and focuses specifically on counters and histograms rather than full APM with tracing and logs. The tradeoff is narrower scope in exchange for dramatically simpler onboarding and lower cost for small or bursty workloads.