Instrumenting your application with OpenTelemetry

Welcome to a hands-on workshop where you'll instrument a multi-service application from scratch with OpenTelemetry, and ship metrics, logs and traces into the VictoriaMetrics stack. Roughly 25% talk, 75% keyboard.

Three parallel tracks: Node.js/Express, Python/Flask and Go. Same system, same backend, same exercises — only the SDK surface differs.

Prerequisites

Comfortable with HTTP APIs and with JavaScript, Python or Go
Docker and Docker Compose installed and working
Git installed on your system
No prior OpenTelemetry, MetricsQL or LogsQL knowledge needed
At least 8GB of free RAM and ~5GB of disk space

Workshop Overview

This workshop consists of 9 modules that take you from a service emitting nothing at all to one you can debug from telemetry alone. You'll instrument a multi-service system, run an OpenTelemetry Collector as the single ingress point, and query the results in VictoriaMetrics, VictoriaLogs, VictoriaTraces and Grafana:

Every module is written once for all three tracks. Use the track switcher in the navigation bar of any module page to flip the code examples between Node.js, Python and Go — your choice is remembered as you move through the workshop.

Module 1

Observability and OpenTelemetry

What observability means, the three signals it relies on — metrics, logs and traces — and what OpenTelemetry is.

Module 2

Setup and Sanity Check

Start the whole stack, your API included, with one Docker Compose command, and check with the doctor script that everything is up and running.

Module 3

The Application You'll Instrument

Tour the todo-api you'll be editing all day — its endpoints, its dependencies and its code.

Module 4

The Easy Path: Zero-Code Auto-Instrumentation

Get all three signals flowing without touching application code.

Module 5

The OpenTelemetry Collector

What the OpenTelemetry Collector is, what it can do, and what this workshop's Collector does to your metrics, logs and traces.

Module 6

Manual Metrics

Pick the right instrument, emit business metrics, and meet cardinality before it bites.

Module 7

Manual Logs

Emit structured logs that carry trace context, and query them with LogsQL.

Module 8

Manual Traces

Create custom spans, record errors properly, and propagate context across services and languages.

Module 9

Production Realities and Wrap-Up

Cost, sampling, PII and rollout strategy — what changes when this leaves your laptop.

Getting Started

Start with Module 1, an introduction to observability and OpenTelemetry; Module 2 gets your environment ready
Work through the modules in order — each one builds on the last
Pick the track you want to type in: JavaScript, Python or Go. All three build the same system against the same backend.

Tips for Success

Paste the exact queries from the handout — "just explore the data" comes later
When something looks wrong, read the Collector logs before anything else
You can look at the solutions in the repository

Resources

Workshop Completion

Upon completing all modules, you'll have:

Instrumented a service with metrics, logs and traces, starting from nothing
Run an OpenTelemetry Collector as a single ingress point, fanning out to three backends
Chosen the right instruments and reasoned about cardinality before it hurt
Emitted structured logs that carry trace context, and queried them with LogsQL
Written custom spans and propagated context across service and language boundaries

Congratulations! You'll have gained the confidence to instrument your own services deliberately rather than by accident. This knowledge enables you to:

Add telemetry that answers real questions to services you already own
Design dashboards and alerts around questions, not around whatever was easy to emit
Reason about the cost and cardinality of everything you collect

Contributing

Found an issue, have an improvement idea or want to add more modules? Please open an issue or submit a pull request!

Start with Module 1 →