📊 Telemetry Hub

Biblioteca centralizada para telemetria e logging estruturado padronizado, compatível com múltiplos frameworks (Tsed, SST/Middy).

🔗 Quick Links

- 📘 Guias por Framework:
- Tsed
- SST/Middy
- 📖 Conceitos Core:
- Logging Padronizado
- Tracing Padronizado
- Testes

🎯 Objetivo

Padronizar a forma como logs são gerados em diferentes tipos de projetos, garantindo:
- Consistência nos campos de log entre diferentes implementações
- Observabilidade através do OpenTelemetry
- Facilidade de manutenção com uma única fonte de verdade

📦 Instalação

``bash
npm install @mecanizou/telemetry-hub
`

Envrionment Variables

Defina as seguintes variáveis de ambiente para configurar a telemetria:

`bash

OTEL_EXPORTER_OTLP_ENDPOINT=https://seu-endpoint-otel.com
OTEL_EXPORTER_OTLP_USER=seu-usuario
OTEL_EXPORTER_OTLP_PASS=sua-senha
SERVICE_NAME=my-service # Opcional, default: 'unknown-service' (Tsed) ou 'sst-service' (SST)
STAGE=production # Opcional, default: 'development'
`

🏗️ Arquitetura

`
src/telemetry/
├── core/ # 🎯 Implementação base (StandardLogger, StandardTracer)
│ ├── types.ts # Interface StandardLogData
│ ├── logger.ts # StandardLogger
│ ├── tracer-types.ts # Interface StandardTraceData
│ ├── tracer.ts # StandardTracer
│ ├── index.ts # Exports
│ ├── README.md # 📚 Visão geral do Core
│ ├── LOGGING.md # 📝 Guia de logging
│ ├── TRACING.md # 🔍 Guia de tracing
│ └── __tests__/ # Testes (57 testes, 100% cobertura)
│ ├── logger.test.ts
│ ├── tracer.test.ts
│ ├── logger-types.test.ts
│ └── README.md # 📚 Documentação dos testes
│
├── tsed/ # 🔷 Implementação para Tsed
│ ├── config.ts # TsedTelemetryProvider (logs + traces + métricas)
│ ├── service.ts # TsedTelemetryService
│ ├── log-telemetry.ts # Decorator @TsedLogTelemetry
│ ├── sync-log-record-processor.ts
│ ├── index.ts
│ ├── README.md # 📚 Guia de uso Tsed
│ ├── IMPLEMENTATION_SUMMARY.md # 📝 Resumo da implementação
│ └── SST_COMPARISON.md # 🔄 Comparação Tsed vs SST
│
└── sst/ # 🟦 Implementação para SST/Middy
├── telemetry.ts # Configuração OpenTelemetry + getStandardLogger/Tracer
├── index.ts
├── README.md # 📚 Guia de uso SST
└── middy/
├── middleware.ts # Middleware Middy (usa StandardLogger + StandardTracer)
└── index.ts
`

$3

#### 1. StandardLogger (Core)
- Classe base que formata logs no padrão OpenTelemetry
- Garante que todos os campos seguem a mesma estrutura
- Implementa os métodos: logError, logInfo, logWarn, logDebug

#### 2. StandardLogData (Interface)
Define o contrato padrão de log com campos:
- severity, message, error
- serviceName, environment
- http (method, url, endpoint, statusCode, etc.)
- user (accountUserUid, accountUid, applicationUid)
- execution (requestId, awsRequestId, functionName, controller, etc.)
- performance (durationMs, success)
- context (dados adicionais)

🚀 Uso

$3

`typescript
import {
TsedTelemetryProvider,
TsedTelemetryService,
TsedLogTelemetry
} from '@mecanizou/telemetry-hub';

// 1. Configurar provider (no módulo principal)
@Configuration({
// ...
})
export class Server {
@Inject()
protected telemetryProvider: TsedTelemetryProvider;

async $afterInit() {
await this.telemetryProvider.initialize();
}
}

// 2. Usar decorator nos controllers
export class CheckoutController {
@TsedLogTelemetry()
async getCheckout(@Context() $ctx: ServerlessContext) {
// Erros são capturados e logados automaticamente
return await this.service.execute();
}
}
`

$3

`typescript
import { middyMiddleware } from '@mecanizou/telemetry-hub';
import middy from '@middy/core';

export const handler = middy(async (event, context) => {
// Sua lógica aqui
return { statusCode: 200, body: 'OK' };
}).use(middyMiddleware());
`

O middleware automaticamente:
- Registra logs de INFO em caso de sucesso
- Registra logs de ERROR em caso de falha
- Mantém traces e métricas do OpenTelemetry

⚙️ Configuração

$3

`bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://seu-endpoint-otel.com
OTEL_EXPORTER_OTLP_USER=seu-usuario
OTEL_EXPORTER_OTLP_PASS=sua-senha
`

$3

`bash
SERVICE_NAME=my-service # Default: 'unknown-service' (Tsed) ou 'sst-service' (SST)
STAGE=production # Default: 'development'
`

✅ Testes

O projeto possui 79 testes com 100% de cobertura:

- Core: 57 testes (logger, tracer, tipos)
- SST: 9 testes (integração, singleton, forceFlush)
- Tsed: 13 testes (provider, service, integração)

Para executar:
`bash
npm test # Executar todos os testes
npm run test:watch # Modo watch
npm run test:ui # UI interativa
npm run test:coverage # Relatório de cobertura
`

📝 Campos Padronizados de Log

Todos os logs exportam os seguintes atributos OpenTelemetry:

`typescript
{
// Identificação
timestamp: "2024-12-05T10:30:00.000Z",
"service.name": "cart-service",
"deployment.environment.name": "production",

// Erro (quando aplicável)
"error.type": "ValidationError",
"error.message": "Invalid cart item",
"error.stack": "...",

// HTTP
"http.method": "POST",
"http.url": "/api/cart/checkout",
"http.endpoint": "/api/cart/checkout",
"http.status_code": 400,

// Usuário
"accountUser.uid": "user-123",
"account.uid": "account-456",
"application.uid": "app-789",

// Execução
"request.id": "req-abc",
"aws.request.id": "aws-xyz",
"function.name": "checkoutHandler",
"function.invocation.id": "inv-123",
"controller.name": "CheckoutController",
"controller.method": "getCheckout",
"origin": "mobile",

// Performance
"duration.ms": 234,
"execution.success": true,

// Contexto adicional
"context": "{...}"
}
`

🔄 Compatibilidade

| Framework | Versão Testada | Status |
|-----------|---------------|--------|
| Tsed | ^8.19.4 | ✅ |
| SST/Middy | ^6.4.5 | ✅ |
| OpenTelemetry | ^0.56.0 | ✅ |

📚 Documentação Adicional

> 📖 Guia de Navegação da Documentação - Mapa completo de toda documentação disponível

$3

1. Clone o repositório
2. Instale dependências: npm install
3. Execute testes: npm test
4. Execute verificação de tipo: npm run test:tsc
5. Formate código: npm run fix`

📄 Licença

ISC