@luidev02/atlas-sdk

Cliente Node.js para Atlas, la plataforma de identidad, configuración y observabilidad para servicios distribuidos. Autentica el proceso contra el control plane, resuelve la configuración declarada por el servicio (recursos, credenciales y permisos) y exporta trazas distribuidas por HTTP.

Sin dependencias de terceros: solo módulos de la propia biblioteca de Node (node:http, node:https, node:crypto, node:async_hooks, node:fs, node:os, node:url, node:path, node:perf_hooks, node:v8 y alguno más). Nada que npm install tenga que descargar.

• Versión: 0.9.0
• Runtime: Node.js ≥ 20.19 · ESM, cargable también con require()
• Protocolo: HTTP/JSON contra la API /v1 de Atlas
• Propagación: W3C Trace Context (traceparent), compatible con OpenTelemetry y equivalentes
• Documentación completa: atlas.kyracloud.com

Este README cubre solo lo necesario para instalar y arrancar un servicio. La referencia completa de la API, las guías de instrumentación, el modelo de fallos, permisos, variables de entorno y las recetas de diagnóstico viven en la documentación.

Requisitos

| | | |---|---| | Node.js | ≥ 20.19.0 — se usan AsyncLocalStorage y node:http/https sin polyfills | | Sistema de módulos | ESM o CommonJS: el paquete es ESM, y desde Node 20.19 require() lo carga igual | | Control plane | Una instancia de Atlas accesible por HTTP o HTTPS |

Conseguir una instancia

Este paquete es el cliente: necesita una instancia de Atlas contra la que hablar. Se contrata como instancia dedicada —con su base de datos y su panel, sin compartir servidor con otros clientes— en kyracloud.com: te registras, contratas el servicio y se te aprovisiona.

De ahí salen los dos valores que necesita el SDK: la dirección de tu panel (ATLAS_URL) y la clave de agente que emitas desde él (ATLAS_TOKEN).

Instalación

npm install @luidev02/atlas-sdk
# pnpm add @luidev02/atlas-sdk
# yarn add @luidev02/atlas-sdk

Inicio rápido

import express from 'express';
import { createAtlasClient, atlas } from '@luidev02/atlas-sdk';

const client = createAtlasClient({
  token: process.env.ATLAS_TOKEN,               // atlas_ak_… o atlas_bt_…
  serviceName: process.env.ATLAS_SERVICE_NAME,  // solo con clave de agente
  url: process.env.ATLAS_URL,
});

// Autentica, resuelve la configuración y arranca el heartbeat.
await client.init();

const app = express();
app.use(atlas.express());          // una transaction por request
app.use(routes);
app.use(atlas.errorMiddleware());  // adjunta la excepción real al span

app.listen(3000);

process.on('SIGTERM', async () => {
  await client.close();            // vacía la cola de spans y cierra la sesión
  process.exit(0);
});

En un proyecto CommonJS es lo mismo, sin transpilar ni import() dinámico:

const { createAtlasClient, atlas } = require('@luidev02/atlas-sdk');

El SDK no lee ATLAS_TOKEN ni ATLAS_URL por su cuenta: los valores se pasan a createAtlasClient(). El nombre de esas variables es una convención, no un contrato — el detalle de qué variables sí lee el SDK está en Variables de entorno.

Trazas entre servicios, en resumen

Cuando un servicio instrumentado llama a otro, la traza los atraviesa a los dos y se ve como una sola línea de tiempo. El enlace viaja en traceparent, la cabecera del estándar W3C que hablan OpenTelemetry, Elastic y las demás herramientas de tracing: el SDK la lee en cada petición entrante y la escribe en cada llamada saliente por un fetch instrumentado, sin configurar nada.

Como el formato es el estándar, funciona en los dos sentidos aunque el otro servicio no use Atlas — uno instrumentado con OpenTelemetry, en cualquier lenguaje, puede ser el padre de una traza de Atlas o continuarla.

Cuando los dos extremos usan el SDK, el Service Map los dibuja conectados como servicios, no como una API de terceros: el servicio llamado anuncia su nombre en cada respuesta y quien lo llama lo reconoce, sin configurar nada. Y las llamadas al propio control plane de Atlas no se trazan — el sistema que observa no aparece como una dependencia del servicio observado.

Muestreo, en resumen

createAtlasClient({ /* … */ sampleRate: 0.1 });   // 1 de cada 10 trazas, entera

Baja el volumen sin mover las métricas: las transactions se envían siempre (son las que alimentan latencia, throughput, tasa de error y alertas) y lo que se descarta son los spans hijos, que es donde está el volumen. Lo que falló tampoco se descarta nunca. Detalle en Muestreo.

Credenciales, en resumen

Hay dos tipos de credencial, distinguidos por su prefijo: atlas_ak_… (clave de agente, cubre todos los servicios de una organización y ambiente; requiere serviceName) y atlas_bt_… (bootstrap, ligada a un único servicio ya dado de alta). Guía completa, con alcance, emisión y resolución: Credenciales.

Instrumentación automática, en resumen

const fetchInstrumentado = atlas.instrumentFetch();  // envuelve globalThis.fetch
atlas.instrumentPg(pool);                            // node-postgres
atlas.instrumentMysql(pool);                         // mysql2 y mysql2/promise
atlas.collectDbMetrics(pool, { system: 'postgres' }); // salud del servidor, no de las consultas

Métricas de proceso (CPU, memoria, event loop) y de la máquina donde corre el proceso se reportan solas, en cada latido — sin llamar a nada.

Las llamadas salientes a terceros (una API que consumes por fetch) registran qué mandaste, qué te respondió y con qué status — de cada llamada, para poder auditar e investigar después. Se lee de un clon de la respuesta, así que nunca le roba el body a tu código:

createAtlasClient({ /* … */ captureFetchBody: 'all' });  // 'all' (por defecto) | 'errors' | 'off'

Guías paso a paso: Instrumentar Express y Instrumentar bases de datos.

Logs, en resumen

Logs correlacionados con la traza en curso: cada log lleva el trace_id/span_id de la petición que lo emitió, así en el panel se salta de una traza a lo que el servicio iba escribiendo mientras la atendía.

import { atlas } from '@luidev02/atlas-sdk';

atlas.log.info('pedido recibido', { orderId, userId });
atlas.log.error('fallo al cobrar', { orderId, gateway: 'stripe' });

Niveles: trace · debug · info · warn · error · fatal. Se envían por lotes con el mismo cliente HTTP propio del exportador (no el fetch instrumentado, para no auto-observarse) y son best-effort: un log nunca bloquea ni tumba la aplicación. Fuera de una petición (un job, el arranque) el log se guarda igual, sin traza.

Para reenviar lo que la app ya escribe por consola, sin tocar su código:

atlas.captureConsole();            // console.log/info/warn/error → también a Atlas

console sigue funcionando exactamente igual; solo se añade el envío.

Trazas manuales, en resumen

import { span } from '@luidev02/atlas-sdk';

const rows = await span.run(
  'SELECT clientes',
  { type: 'db', subtype: 'postgres', action: 'query' },
  async (s) => {
    const result = await pool.query('SELECT * FROM clientes WHERE id = $1', [id]);
    s.setDb({ system: 'postgres', statement: 'SELECT * FROM clientes WHERE id = $1', rows_affected: result.rowCount });
    return result.rows;
  },
);

Referencia completa del span y de createAtlasClient(options): API del cliente, API del span, createAtlasClient.

El resto vive en la documentación

Contrato de dependencias, permisos, modelo de fallos, qué se captura y qué se redacta, secuencia de arranque, apagado ordenado, diagnóstico, catálogo de errores y compatibilidad — todo con más detalle del que cabe en un README:

• Qué es Atlas — conceptos y arquitectura
• Tu primer servicio — tutorial completo
• Contrato de dependencias
• Alertas y avisos
• Despliegue
• Catálogo de errores
• Modo solo telemetría y demás recetas de diagnóstico

Enlaces

• Paquete en npm
• Documentación completa

Licencia

MIT