Ingesta Manual mediante API REST 🔌

Para desarrolladores que no utilizan OpenTelemetry o que prefieren instrumentar de manera manual e ingresar métricas, trazas o logs directamente a través de peticiones HTTP tradicionales de alto rendimiento, API Monitor APM expone un conjunto de endpoints REST JSON unificados.

---

🔒 Seguridad y Autorización

Todas las peticiones HTTP enviadas a los endpoints de la API deben autenticarse de forma obligatoria adjuntando tu token de API del Workspace en la cabecera:

api-key-newinntech: TU_API_KEY_AQUÍ

La URL base de la API de ingesta es: http://localhost:3000/api/v1/telemetry (reemplaza localhost:3000 por tu host de producción).

---

📡 Endpoints de Ingesta Manual

1. Ingesta de Trazas (Traces & Spans)

• Ruta: POST /traces
• Payload (JSON):

  {
    "serviceName": "mi-servicio-personalizado",
    "environment": "production",
    "spans": [
      {
        "traceId": "5f280d19e6e29f59ceb4b4eeb8d86921",
        "spanId": "dd9081f5986d98c5",
        "parentId": "",
        "name": "GET /api/data",
        "startTimeUnixNano": "1784219768469000000",
        "endTimeUnixNano": "1784219768499000000",
        "status": {
          "code": "OK"
        },
        "attributes": {
          "http.method": "GET",
          "http.status_code": 200
        }
      }
    ]
  }

2. Ingesta de Logs

• Ruta: POST /logs
• Payload (JSON):

  {
    "serviceName": "mi-servicio-personalizado",
    "environment": "production",
    "logs": [
      {
        "timestampUnixNano": "1784219768469000000",
        "severity": "INFO",
        "traceId": "5f280d19e6e29f59ceb4b4eeb8d86921",
        "spanId": "dd9081f5986d98c5",
        "body": "Petición procesada exitosamente en el servidor",
        "attributes": {
          "component": "http-handler"
        }
      }
    ]
  }

3. Ingesta de Métricas

• Ruta: POST /metrics
• Payload (JSON):

  {
    "serviceName": "mi-servicio-personalizado",
    "environment": "production",
    "metrics": [
      {
        "name": "cpu.utilization",
        "type": "gauge",
        "dataPoints": [
          {
            "timestampUnixNano": "1784219768469000000",
            "value": 42.5,
            "attributes": {
              "core": "cpu0"
            }
          }
        ]
      }
    ]
  }

---

📟 Ejemplo de Consumo en Node.js (JavaScript)

El siguiente script completo e independiente muestra cómo enviar trazas y logs correlacionados utilizando la librería axios en Node.js de forma manual:

const axios = require('axios');

const API_KEY = '68de6b3c-1be3-45c8-a80c-a19d333f49ec'; // Tu API Key
const BASE_URL = 'http://localhost:3000/api/v1/telemetry';

async function sendManualTelemetry() {
  const traceId = '5f280d19e6e29f59ceb4b4eeb8d86921';
  const spanId = 'dd9081f5986d98c5';
  const nowNano = String(Date.now() * 1000000);

  const headers = {
    'Content-Type': 'application/json',
    'api-key-newinntech': API_KEY
  };

  try {
    // 1. Enviar Span de Traza manual
    await axios.post(`${BASE_URL}/traces`, {
      serviceName: 'my-custom-node-app',
      environment: 'production',
      spans: [{
        traceId,
        spanId,
        parentId: '',
        name: 'database-query-test',
        startTimeUnixNano: nowNano,
        endTimeUnixNano: String(Number(nowNano) + 15000000), // Duración 15ms
        status: { code: 'OK' },
        attributes: { 'db.system': 'postgresql', 'db.operation': 'SELECT' }
      }]
    }, { headers });

    // 2. Enviar Log correlacionado
    await axios.post(`${BASE_URL}/logs`, {
      serviceName: 'my-custom-node-app',
      environment: 'production',
      logs: [{
        timestampUnixNano: nowNano,
        severity: 'INFO',
        traceId,
        spanId,
        body: 'Conexión a base de datos establecida y consulta SELECT ejecutada',
        attributes: { 'module': 'db-connector' }
      }]
    }, { headers });

    console.log('✅ Telemetría manual reportada con éxito a API Monitor.');
  } catch (error) {
    console.error('❌ Error en el reporte de telemetría:', error.response ? error.response.data : error.message);
  }
}

sendManualTelemetry();

---

🐍 Ejemplo de Consumo en Python

El siguiente script muestra cómo reportar métricas físicas personalizadas a API Monitor utilizando la librería estándar de requests en Python:

import requests
import time

API_KEY = "68de6b3c-1be3-45c8-a80c-a19d333f49ec" # Tu API Key
BASE_URL = "http://localhost:3000/api/v1/telemetry"

def send_python_metrics():
    now_nano = str(int(time.time() * 1000000000))
    
    headers = {
        "Content-Type": "application/json",
        "api-key-newinntech": API_KEY
    }
    
    payload = {
        "serviceName": "python-worker-service",
        "environment": "production",
        "metrics": [
            {
                "name": "worker.memory.usage",
                "type": "gauge",
                "dataPoints": [
                    {
                        "timestampUnixNano": now_nano,
                        "value": 256.45, # RAM en MB
                        "attributes": {
                            "process.name": "celery-worker-1",
                            "region": "us-east-1"
                        }
                    }
                ]
            }
        ]
    }
    
    try:
        response = requests.post(f"{BASE_URL}/metrics", json=payload, headers=headers)
        if response.status_code == 202:
            print("✅ Métricas físicas de Python reportadas con éxito.")
        else:
            print(f"⚠️ Error {response.status_code}: {response.text}")
    except Exception as e:
        print(f"❌ Error de conexión: {str(e)}")

send_python_metrics()