> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Instrumentar una aplicación con Managed ClickStack
> Guía para instrumentar una aplicación Node.js con OpenTelemetry y enviar logs, métricas y trazas a Managed ClickStack
Esta guía muestra cómo instrumentar una aplicación sencilla de Node.js con OpenTelemetry y enviar sus logs, métricas y trazas a [Managed ClickStack](/es/clickstack/getting-started/managed). El backend se instrumenta sin necesidad de hacer cambios en el código fuente de la aplicación.
[HackerNews Analyzer](https://github.com/ClickHouse/hn-news-analyzer) es una pequeña aplicación de Node.js que consulta el conjunto de datos de HackerNews alojado en la instancia de demo pública de ClickHouse. Cada gráfico, tabla y cuadro de búsqueda está respaldado por una consulta real de ClickHouse, por lo que cada interacción genera una traza cuyo span principal es la llamada HTTPS del backend a ClickHouse.
## Requisitos previos
* Un OTel collector disponible y accesible, que ingiera datos en su servicio de Managed ClickStack. Necesita su endpoint de OTLP y un token de ingestión.
* Node 18+ y npm.
## Clona y ejecuta la aplicación
Clona el repositorio, instala las dependencias y crea el archivo `.env`:
```bash theme={null}
git clone https://github.com/ClickHouse/hn-news-analyzer.git
cd hn-news-analyzer
npm install
cp .env.example .env
```
La fuente de datos de ClickHouse usa de forma predeterminada el clúster demo público y de solo lectura, por lo que la aplicación funciona sin necesidad de configuración adicional. Iníciala:
```bash theme={null}
./run.sh
```
Abre [http://localhost:5001](http://localhost:5001). Verás un selector de año, estadísticas resumidas, un gráfico de actividad, tablas de usuarios y dominios principales, y un cuadro de búsqueda. Explora la aplicación: cambia de año y profundiza en las historias.
En este punto, la aplicación se está ejecutando, pero aún no está instrumentada. ClickStack no muestra datos: está esperando telemetría. Este es el estado "anterior".
## Obtén los detalles de conexión
La aplicación necesita dos valores para conectarse al colector:
* `OTEL_EXPORTER_OTLP_ENDPOINT`: el endpoint de OTLP que expone tu colector (normalmente el puerto `4318` para OTLP sobre HTTP).
* `OTEL_EXPORTER_OTLP_HEADERS`: el encabezado de autorización que contiene tu token de ingestión, con el formato `authorization=`.
Abre `.env` y configúralos:
```bash theme={null}
OTEL_SERVICE_NAME=hn-analyzer-api
OTEL_EXPORTER_OTLP_ENDPOINT=https://:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=
```
El SDK usa `OTEL_EXPORTER_OTLP_HEADERS` para establecer el encabezado de autorización para las tres señales: trazas, métricas y logs. Si el collector se ejecuta localmente y no exige autenticación, puedes dejar el valor vacío (`OTEL_EXPORTER_OTLP_HEADERS=authorization=`), pero la variable debe estar presente; el SDK omite por completo la inicialización si no está definida o si está completamente vacía.
## Instrumentar la aplicación
La instrumentación consta de tres partes: instalar los SDKs, cambiar el comando de inicio y habilitar el SDK para navegador. Nada de esto cambia la lógica de negocio de la aplicación.
### Instalar los SDKs
Instala los SDKs de OpenTelemetry tanto para backend como para navegador:
```bash theme={null}
npm install @hyperdx/node-opentelemetry @hyperdx/browser
```
### Usa la CLI de opentelemetry-instrument
La aplicación se inicia con `run.sh`, que tiene dos líneas `exec` al final: una activa y otra comentada. Cambia cuál de ellas está activa para que Node se ejecute a través de `opentelemetry-instrument`:
```diff theme={null}
# BEFORE: plain node, no instrumentation, collector stays silent:
-exec node scripts/entrypoint.js
+# exec node scripts/entrypoint.js
# AFTER: same source, wrapped by opentelemetry-instrument CLI.
-# exec npx opentelemetry-instrument scripts/entrypoint.js
+exec npx opentelemetry-instrument scripts/entrypoint.js
```
Ese es todo el cambio en el backend. La autoinstrumentación se carga mediante `opentelemetry-instrument` al iniciar el proceso.
### Habilita el SDK para navegador
Para capturar trazas distribuidas (del navegador al backend) y repeticiones de sesión, habilita el SDK para navegador en `src/web/telemetry.ts`. Descomenta la importación y el bloque `HyperDX.init({...})`:
```javascript theme={null}
import HyperDX from '@hyperdx/browser';
export function initTelemetry(): void {
HyperDX.init({
url: __OTLP_ENDPOINT__,
apiKey: __OTLP_AUTH_TOKEN__,
service: 'hn-analyzer-web',
tracePropagationTargets: [/localhost:5001/i, /\/api\//i],
consoleCapture: true,
advancedNetworkCapture: true,
});
}
```
No se requiere editar `.env` adicionalmente. `__OTLP_ENDPOINT__` y `__OTLP_AUTH_TOKEN__` son constantes de tiempo de compilación inyectadas por `vite.config.ts`: el endpoint es `OTEL_EXPORTER_OTLP_ENDPOINT` y el token se obtiene de `OTEL_EXPORTER_OTLP_HEADERS`, los mismos valores que usa el backend.
El token de ingestión está integrado en el bundle público del navegador y cualquiera puede verlo al inspeccionar la pestaña Network.
## Generar tráfico y ver la telemetría
Reinicia la aplicación para que el nuevo comando de inicio y el paquete del navegador recién compilado surtan efecto:
```bash theme={null}
# Ctrl-C the previous run, then:
./run.sh
```
Recarga la pestaña del navegador para que Vite sirva el bundle actualizado; luego recarga la aplicación unas cuantas veces, cambia de año y haz clic en las historias para generar tráfico.
Abre la UI de ClickStack:
1. Ve a **Búsqueda** y filtra por los últimos 5 minutos. Los logs de `hn-analyzer-api` empezarán a aparecer.
2. Haz clic en una petición y sube por la traza. Verás el span del handler de Express, un span HTTP hijo que apunta al clúster de ClickHouse con la duración real de la red, y registros de `console.log` correlacionados en la misma traza.
3. Abre **Session Replay** para reproducir un video de una sesión del navegador por el que puedes desplazarte, sincronizado con la cronología de la traza.
Los logs, las métricas, las trazas y las repeticiones de sesión aparecen en la misma UI, comparten el mismo lenguaje de consulta y se correlacionan automáticamente.
## Más información
* [Session Replay](/es/clickstack/features/session-replay): descripción general de la funcionalidad, opciones de SDK y controles de privacidad.
* [Session Replay Demo](/es/clickstack/example-datasets/session-replay): una demo autónoma con una instancia local de ClickStack.
* [Primeros pasos con ClickStack](/es/clickstack/getting-started/index): despliegue de ClickStack e ingesta de tus primeros datos.
* [Todos los conjuntos de datos de ejemplo](/es/clickstack/example-datasets/index): otros conjuntos de datos de ejemplo y guías.