From 7f24676e73e7ef33e151b276a9264e21319f2a7f Mon Sep 17 00:00:00 2001
From: Khuyen Tran <khuyentran@codecut.ai>
Date: Mon, 22 Jun 2026 11:31:24 +0700
Subject: [PATCH] docs: add OpenTelemetry how-to page for exporting nic traces

---
 docs/docs/how-tos/opentelemetry.mdx | 59 +++++++++++++++++++++++++++++
 docs/sidebars.js                    |  1 +
 2 files changed, 60 insertions(+)
 create mode 100644 docs/docs/how-tos/opentelemetry.mdx

diff --git a/docs/docs/how-tos/opentelemetry.mdx b/docs/docs/how-tos/opentelemetry.mdx
new file mode 100644
index 00000000..8a69b897
--- /dev/null
+++ b/docs/docs/how-tos/opentelemetry.mdx
@@ -0,0 +1,59 @@
+---
+title: OpenTelemetry
+slug: /how-tos/opentelemetry
+description: "Export OpenTelemetry traces from nic with the OTEL_EXPORTER and OTEL_ENDPOINT env vars: console, OTLP, or both, including sending to a local collector."
+---
+
+To debug a slow or failing deploy, you can have `nic` emit a **trace**: a timeline of its work. Using [OpenTelemetry](https://opentelemetry.io/), an open standard, it records each step it runs (parsing your config, calling your cloud provider, each deploy stage) with how long it took and whether it failed.
+
+By default `nic` collects these traces but doesn't export them. This page covers how to export them: choosing an exporter, setting the endpoint, and sending to a local collector.
+
+## Choose an exporter
+
+An exporter controls where `nic` sends its traces. Set `OTEL_EXPORTER` to one of:
+
+| Value | Behavior |
+|---|---|
+| `none` (default) | Records traces but sends them nowhere. |
+| `console` | Sends traces to your terminal (pretty-printed stdout). |
+| `otlp` | Sends traces to a collector over OTLP gRPC, at the address in `OTEL_ENDPOINT`. |
+| `both` | Sends traces to your terminal and a collector. |
+
+Set `OTEL_EXPORTER` on the command you run, to print traces for a single deploy:
+
+```bash
+OTEL_EXPORTER=console nic deploy -f <config-file>
+```
+
+Or set it in your `.env` so it applies to every `nic` run from that directory:
+
+```bash
+# .env
+OTEL_EXPORTER=console
+```
+
+## Send traces to a collector
+
+A collector is a separate process that receives your traces and sends them on to a tracing backend for storage and viewing.
+
+For `otlp` and `both`, `nic` sends traces over **OTLP gRPC** to the collector address in `OTEL_ENDPOINT`, which defaults to `localhost:4317`.
+
+### Local collector
+
+To capture traces locally, run a collector with an OTLP gRPC receiver on `localhost:4317`. That is the default endpoint, so you set only the exporter:
+
+```bash
+OTEL_EXPORTER=otlp nic deploy -f <config-file>
+```
+
+### Remote collector
+
+To send to a collector elsewhere, set `OTEL_ENDPOINT` to its address alongside `OTEL_EXPORTER`:
+
+```bash
+OTEL_EXPORTER=otlp \
+  OTEL_ENDPOINT=otel-collector.example.com:4317 \
+  nic deploy -f <config-file>
+```
+
+Set `OTEL_EXPORTER=both` to watch traces in your terminal and send them to the collector at the same time.
diff --git a/docs/sidebars.js b/docs/sidebars.js
index bf526290..aa219fcb 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -47,6 +47,7 @@ module.exports = {
         "how-tos/deploy-cluster",
         "how-tos/update-cluster",
         "how-tos/destroy-cluster",
+        "how-tos/opentelemetry",
         {
           type: "category",
           label: "Providers",