{"id":21861471,"url":"https://github.com/ozmap/ozlogger","last_synced_at":"2026-04-24T22:36:21.174Z","repository":{"id":64805851,"uuid":"562654201","full_name":"ozmap/ozlogger","owner":"ozmap","description":"DevOZ logger module.","archived":false,"fork":false,"pushed_at":"2026-03-10T19:26:06.000Z","size":726,"stargazers_count":2,"open_issues_count":18,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2026-03-11T00:58:53.580Z","etag":null,"topics":["logger","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ozmap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"Agents.md","dco":null,"cla":null}},"created_at":"2022-11-07T00:58:09.000Z","updated_at":"2026-03-03T02:50:12.000Z","dependencies_parsed_at":"2024-02-11T04:26:49.903Z","dependency_job_id":"66b76190-cac4-4b64-b2cc-a0078847acaa","html_url":"https://github.com/ozmap/ozlogger","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/ozmap/ozlogger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozmap%2Fozlogger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozmap%2Fozlogger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozmap%2Fozlogger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozmap%2Fozlogger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ozmap","download_url":"https://codeload.github.com/ozmap/ozlogger/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozmap%2Fozlogger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32243558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["logger","nodejs","typescript"],"created_at":"2024-11-28T03:11:44.609Z","updated_at":"2026-04-24T22:36:21.168Z","avatar_url":"https://github.com/ozmap.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OZLogger\n\n[![npm version](https://img.shields.io/npm/v/@ozmap/logger.svg)](https://www.npmjs.com/package/@ozmap/logger)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nMódulo de logging profissional para Node.js desenvolvido pela DevOZ. Projetado para ambientes de produção com suporte a OpenTelemetry, saída JSON estruturada, colorização de terminal, e controle dinâmico de níveis de log via HTTP.\n\n---\n\n## Propósito e Filosofia\n\nO OZLogger foi desenvolvido com o objetivo de **criar uma forma padronizada de auditoria** em aplicações Node.js, utilizando ferramentas e padrões da indústria como o **OpenTelemetry Data Model**.\n\n### Princípio Fundamental: Minimalismo\n\n\u003e **\"Garantir o log e auditoria básicos, com o menor footprint possível.\"**\n\nO OZLogger foi projetado com uma filosofia clara: **ser o mais leve possível**, tanto em consumo de **memória** quanto de **CPU**. O foco é **apenas externalizar os dados** para stdout/stderr e deixar que os **coletores de logs** (Filebeat, Fluentd, Promtail, etc.) façam o trabalho pesado de transportar, processar e armazenar os logs.\n\n```mermaid\nflowchart LR\n    subgraph App[\"Aplicação\"]\n        OZLogger[\"OZLogger\\n(mínimo footprint)\"]\n    end\n    \n    subgraph Output[\"Saída\"]\n        stdout[\"stdout/stderr\"]\n    end\n    \n    subgraph Collectors[\"Coletores\"]\n        FB[\"Filebeat\"]\n        FD[\"Fluentd\"]\n        PT[\"Promtail\"]\n    end\n    \n    subgraph Destinations[\"Destinos\"]\n        ES[\"Elasticsearch\"]\n        DD[\"Datadog\"]\n        Loki[\"Grafana Loki\"]\n        CW[\"CloudWatch\"]\n    end\n    \n    OZLogger --\u003e|\"≈ 0 overhead\"| stdout\n    stdout --\u003e FB\n    stdout --\u003e FD\n    stdout --\u003e PT\n    FB --\u003e ES\n    FD --\u003e DD\n    PT --\u003e Loki\n    FB --\u003e CW\n```\n\n### Por que Minimalismo?\n\n| Aspecto | Abordagem OZLogger | Benefício |\n|---------|-------------------|----------|\n| **Memória** | Sem buffers internos, sem filas | Memória disponível para a aplicação |\n| **CPU** | Zero processamento de transporte | CPU disponível para a aplicação |\n| **I/O** | Apenas stdout síncrono | Sem conexões de rede, sem arquivos |\n| **Dependências** | Mínimas (apenas @opentelemetry/api) | Menor bundle, menos vulnerabilidades |\n| **Complexidade** | Delega transporte para coletores | Menos código = menos bugs |\n\n### Controle de Nível em Runtime: Feature Crítica\n\nUma das features mais importantes do OZLogger é a capacidade de **alterar o nível de log em runtime** com **tempo de vida (TTL) obrigatório**:\n\n```bash\n# Ativa debug por 5 minutos em produção - sem redeploy!\ncurl -X POST http://localhost:9898/changeLevel \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"level\": \"debug\", \"duration\": 300000}'\n```\n\n**Por que isso é crítico?**\n\n1. **Debug em produção sem redeploy** - Investigue problemas sem derrubar o serviço\n2. **TTL obrigatório** - Impede que alguém esqueça o logger em modo debug\n3. **Propagação automática em cluster** - Todos os workers mudam simultaneamente\n4. **Zero downtime** - Mudança instantânea, reversão automática\n\n### Principais Objetivos\n\n- **Auditoria Padronizada** - Logs estruturados em formato JSON seguindo o padrão OpenTelemetry, permitindo integração com ferramentas de observabilidade como Elasticsearch, Datadog, Splunk, entre outras\n- **Rastreabilidade** - Integração nativa com distributed tracing através de `traceId` e `spanId`, possibilitando correlacionar logs entre diferentes serviços\n- **Compliance** - Nível `audit` dedicado para logs de auditoria, facilitando conformidade com requisitos regulatórios (LGPD, SOC2, etc.)\n- **Segurança** - Funções `mask()` e `filter()` para garantir que dados sensíveis não vazem em logs\n- **Operabilidade** - Controle dinâmico de níveis de log via HTTP, permitindo debugging em produção sem redeploy\n\n### Compatibilidade com Ferramentas de Auditoria\n\nA saída JSON do OZLogger é compatível com:\n\n| Ferramenta | Integração |\n|------------|------------|\n| Elasticsearch/Kibana | Direta via Filebeat ou Logstash |\n| Datadog | Via DD Agent ou API |\n| Splunk | Via Universal Forwarder |\n| AWS CloudWatch | Via CloudWatch Agent |\n| Google Cloud Logging | Via Logging Agent |\n| Grafana Loki | Via Promtail |\n\n---\n\n## Tabela de Conteúdos\n\n- [Características](#características)\n- [Instalação](#instalação)\n- [Quick Start](#quick-start)\n- [Arquitetura do Projeto](#arquitetura-do-projeto)\n- [Estrutura de Arquivos](#estrutura-de-arquivos)\n- [Níveis de Log](#níveis-de-log)\n- [Métodos Disponíveis](#métodos-disponíveis)\n- [Formatos de Saída](#formatos-de-saída)\n- [Servidor HTTP Embarcado](#servidor-http-embarcado)\n- [Contexto e Tracing](#contexto-e-tracing)\n- [Utilitários](#utilitários)\n- [Variáveis de Ambiente](#variáveis-de-ambiente)\n- [Exemplos de Uso](#exemplos-de-uso)\n- [Desenvolvimento](#desenvolvimento)\n- [Testes](#testes)\n- [Contribuindo](#contribuindo)\n- [Documentação Adicional](#documentação-adicional)\n- [Aviso de Deprecação](#-aviso-de-deprecação)\n\n---\n\n## Características\n\n### Minimalismo e Performance\n\n- **Zero overhead de transporte** - Apenas stdout, coletores fazem o resto\n- **Mínimo footprint de memória** - Sem buffers, sem filas internas\n- **Mínimo footprint de CPU** - Sem processamento de transporte\n- **Dependências mínimas** - Apenas `@opentelemetry/api`\n\n### Funcionalidades\n\n- **Múltiplos níveis de log** - debug, info, audit, warn, error\n- **Saída JSON estruturada** - Compatível com OpenTelemetry Data Model\n- **Saída em texto** - Ideal para desenvolvimento local\n- **Colorização** - Cores ANSI configuráveis para terminal\n- **Servidor HTTP embarcado** - Altere níveis de log em runtime\n- **Suporte a Cluster** - Broadcast de eventos entre workers\n- **Integração OpenTelemetry** - traceId e spanId automáticos\n- **Medição de tempo** - Métodos `time()` e `timeEnd()` integrados\n- **Manipulação de dados sensíveis** - Funções `mask()` e `filter()`\n- **Tratamento de referências circulares** - Serialização JSON segura\n- **TypeScript nativo** - Tipagem completa incluída\n\n### Controle Operacional\n\n- **Alteração de nível em runtime** - Via HTTP sem redeploy\n- **TTL obrigatório** - Reversão automática ao nível original\n- **Cluster-aware** - Propagação automática para workers\n\n---\n\n## Instalação\n\n```bash\nnpm install @ozmap/logger\n```\n\nou com Yarn:\n\n```bash\nyarn add @ozmap/logger\n```\n\nou com pnpm:\n\n```bash\npnpm add @ozmap/logger\n```\n\n---\n\n## Quick Start\n\n### TypeScript\n\n```typescript\nimport createLogger from '@ozmap/logger';\n\nconst logger = createLogger('MeuApp');\n\nlogger.info('Aplicação iniciada');\nlogger.debug('Dados de debug', { userId: 123 });\nlogger.error('Erro encontrado', new Error('Falha na conexão'));\n```\n\n### JavaScript\n\n```javascript\nconst createLogger = require('@ozmap/logger');\n\nconst logger = createLogger('MeuApp');\n\nlogger.info('Aplicação iniciada');\nlogger.debug('Dados de debug', { userId: 123 });\n```\n\n---\n\n## Arquitetura do Projeto\n\n```mermaid\nflowchart TB\n    subgraph OZLogger[\"OZLogger\"]\n        subgraph Core[\"Logger Core\"]\n            LC1[\"Gerenciamento de níveis de log\"]\n            LC2[\"Controle de timers\"]\n            LC3[\"Manutenção de contexto (tracing)\"]\n        end\n        \n        Core --\u003e JSON[\"JSON Formatter\"]\n        Core --\u003e Text[\"Text Formatter\"]\n        Core --\u003e HTTP[\"HTTP Server (Runtime)\"]\n        \n        subgraph Utils[\"Utilities\"]\n            U1[Helpers]\n            U2[Objects]\n            U3[Events]\n            U4[Enums]\n            U5[Types]\n        end\n    end\n```\n\n---\n\n## Estrutura de Arquivos\n\nO projeto está organizado da seguinte forma:\n\n```\nozlogger/\n├── lib/                          # Código fonte principal\n│   ├── index.ts                  # Ponto de entrada - exports\n│   ├── Logger.ts                 # Classe principal do Logger\n│   │\n│   ├── format/                   # Formatadores de saída\n│   │   ├── index.ts              # Factory de formatadores\n│   │   ├── json.ts               # Formatador JSON estruturado\n│   │   └── text.ts               # Formatador texto simples\n│   │\n│   ├── http/                     # Servidor HTTP embarcado\n│   │   ├── server.ts             # Configuração do servidor\n│   │   ├── errors.ts             # Classe HttpError\n│   │   └── routes/\n│   │       └── index.ts          # Rotas disponíveis\n│   │\n│   └── util/                     # Utilitários\n│       ├── Events.ts             # Sistema de eventos\n│       ├── Helpers.ts            # Funções auxiliares\n│       ├── Objects.ts            # Manipulação de objetos\n│       │\n│       ├── enum/                 # Enumerações\n│       │   ├── Colors.ts         # Códigos ANSI de cores\n│       │   ├── LevelTags.ts      # Tags de níveis de log\n│       │   ├── LogLevels.ts      # Níveis e severidades\n│       │   └── Outputs.ts        # Tipos de saída\n│       │\n│       ├── interface/            # Interfaces TypeScript\n│       │   ├── LogContext.ts     # Contexto de logging\n│       │   ├── LoggerColorized.ts # Interface de colorização\n│       │   └── LoggerMethods.ts  # Métodos do Logger\n│       │\n│       └── type/                 # Tipos TypeScript\n│           ├── AbstractLogger.ts # Logger abstrato\n│           ├── Event.ts          # Tipos de eventos\n│           ├── Http.ts           # Tipos HTTP\n│           └── LogWrapper.ts     # Wrapper de logging\n│\n├── tests/                        # Testes automatizados\n│   ├── logger.test.ts            # Testes principais\n│   ├── logger.perf.test.ts       # Testes de performance\n│   └── utils.test.ts             # Testes de utilitários\n│\n├── dist/                         # Código compilado (gerado)\n├── package.json                  # Configurações do pacote\n├── tsconfig.json                 # Configurações TypeScript\n├── jest.config.js                # Configurações de testes\n├── Agents.md                     # Documentação dos agentes\n└── README.md                     # Esta documentação\n```\n\n### Descrição dos Arquivos Principais\n\n#### `lib/Logger.ts`\nClasse principal que implementa toda a lógica de logging:\n- Construtor que aceita tag, cliente de log customizado e opção de desabilitar servidor HTTP\n- Métodos de log: `debug()`, `info()`, `audit()`, `warn()`, `error()`\n- Métodos de timing: `time()`, `timeEnd()`\n- Gerenciamento de contexto: `withContext()`, `getContext()`\n- Configuração dinâmica de níveis via `configure()` e `changeLevel()`\n- Factory function `createLogger()` para criação simplificada\n\n#### `lib/format/json.ts`\nFormatador que produz logs em JSON estruturado compatível com OpenTelemetry:\n- Inclui `severityText`, `severityNumber`, `timestamp`, `body`\n- Suporta `traceId` e `spanId` para distributed tracing\n- Tratamento de referências circulares com `getCircularReplacer()`\n\n#### `lib/format/text.ts`\nFormatador para saída em texto simples:\n- Formato: `[timestamp][LEVEL] tag mensagem`\n- Ideal para leitura humana durante desenvolvimento\n\n#### `lib/http/server.ts`\nServidor HTTP embarcado para controle runtime:\n- Inicia apenas no processo primário (cluster-aware)\n- Porta padrão: 9898\n- Processa requisições JSON e text\n- Tratamento de erros padronizado\n\n#### `lib/http/routes/index.ts`\nRotas HTTP disponíveis:\n- `POST /changeLevel` - Altera nível de log temporariamente\n\n#### `lib/util/Events.ts`\nSistema de eventos para comunicação inter-processos:\n- `registerEvent()` - Registra handlers no processo\n- `broadcastEvent()` - Transmite para todos os workers\n\n#### `lib/util/Helpers.ts`\nFunções utilitárias diversas:\n- `stringify()` / `normalize()` - Conversão de dados\n- `colorized()` - Factory de colorização\n- `level()`, `color()`, `output()` - Leitura de configuração\n- `datetime()` - Geração de timestamps\n- `host()` - Parse de configuração do servidor\n- `getCircularReplacer()` - Tratamento de referências circulares\n\n#### `lib/util/Objects.ts`\nManipulação segura de objetos para logging:\n- `mask()` - Ofusca valores sensíveis (usa SHA1 hash)\n- `filter()` - Remove campos especificados\n\n---\n\n## Níveis de Log\n\nOs níveis seguem o modelo de severidade do OpenTelemetry:\n\n| Nível | Severidade | Descrição |\n|-------|------------|-----------|\n| `quiet` | ∞ | Suprime todos os logs |\n| `error` | 17 | Erros de aplicação |\n| `warn` | 13 | Avisos importantes |\n| `audit` | 12 | Logs de auditoria |\n| `info` | 9 | Informações gerais |\n| `debug` | 5 | Debugging detalhado |\n\nNíveis deprecados (serão removidos em 0.3.x):\n- `critical` (17) → use `error`\n- `http` (8) → use `info`\n- `silly` (1) → use `debug`\n\n---\n\n## Métodos Disponíveis\n\n### Métodos de Logging\n\n```typescript\nlogger.debug(...args: unknown[]): void  // Nível DEBUG\nlogger.info(...args: unknown[]): void   // Nível INFO\nlogger.audit(...args: unknown[]): void  // Nível AUDIT\nlogger.warn(...args: unknown[]): void   // Nível WARNING\nlogger.error(...args: unknown[]): void  // Nível ERROR\n```\n\n### Métodos de Timing\n\n```typescript\nlogger.time(id: string): Logger         // Inicia timer\nlogger.timeEnd(id: string): Logger      // Finaliza timer e loga tempo\n\n// Timing com nível específico\nlogger.debug.timeEnd(id: string)        // Loga no nível DEBUG\nlogger.error.timeEnd(id: string)        // Loga no nível ERROR\n```\n\n### Métodos de Contexto\n\n```typescript\nlogger.withContext(ctx: LogContext): Logger  // Adiciona contexto\nlogger.getContext(): LogContext              // Recupera contexto atual\n```\n\n### Métodos de Controle\n\n```typescript\nlogger.changeLevel(level: string): void  // Altera nível de log\nlogger.stop(): Promise\u003cvoid\u003e             // Para servidor HTTP\n```\n\n---\n\n## Formatos de Saída\n\n### JSON (Padrão)\n\n```json\n{\n  \"timestamp\": \"2024-01-15T10:30:00.000Z\",\n  \"tag\": \"MeuApp\",\n  \"severityText\": \"INFO\",\n  \"severityNumber\": 9,\n  \"body\": {\n    \"0\": \"Mensagem de log\",\n    \"1\": { \"dados\": \"adicionais\" }\n  },\n  \"traceId\": \"abc123...\",\n  \"spanId\": \"def456...\",\n  \"pid\": 12345,\n  \"ppid\": 12344\n}\n```\n\n### Text\n\n```\n2024-01-15T10:30:00.000Z [INFO] MeuApp Mensagem de log { dados: \"adicionais\" }\n```\n\n---\n\n## Servidor HTTP Embarcado\n\nO logger inclui um servidor HTTP para controle runtime.\n\n### Configuração\n\n| Variável | Descrição | Padrão |\n|----------|-----------|--------|\n| `OZLOGGER_SERVER` | Porta/endereço | `9898` |\n| `OZLOGGER_HTTP` | Habilita servidor | `true` |\n\nFormatos de `OZLOGGER_SERVER`:\n- `9898` - Apenas porta\n- `:9898` - Apenas porta\n- `localhost:9898` - Host e porta\n- `127.0.0.1:9898` - IPv4 e porta\n- `[::1]:9898` - IPv6 e porta\n\n### Desabilitar Servidor\n\nVia variável de ambiente:\n```bash\nOZLOGGER_HTTP=\"false\"\n```\n\nVia código:\n```typescript\nconst logger = createLogger('app', { noServer: true });\n```\n\n### Alterar Nível em Runtime\n\n```bash\ncurl -X POST http://localhost:9898/changeLevel \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"level\": \"debug\", \"duration\": 300000}'\n```\n\nO nível retorna ao original após `duration` milissegundos.\n\n---\n\n## Contexto e Tracing\n\n### OpenTelemetry Integration\n\nO logger integra automaticamente com OpenTelemetry para distributed tracing:\n\n```typescript\nimport { trace, context } from '@opentelemetry/api';\n\n// TraceId e SpanId são adicionados automaticamente aos logs\n// quando existe um span ativo no contexto\nlogger.info('Requisição processada');\n```\n\n### Contexto Manual\n\n```typescript\nlogger.withContext({\n  traceId: 'custom-trace-id',\n  spanId: 'custom-span-id',\n  attributes: {\n    userId: 123,\n    requestId: 'abc'\n  }\n});\n\nlogger.info('Log com contexto personalizado');\n```\n\n---\n\n## Utilitários\n\n### mask() - Ofuscar Dados Sensíveis\n\n```typescript\nimport { mask } from '@ozmap/logger';\n\nconst dados = {\n  usuario: 'admin',\n  senha: 'secret123',\n  apiKey: 'key123'\n};\n\nconst seguro = mask(dados, ['senha', 'apiKey']);\n// {\n//   usuario: 'admin',\n//   senha: '****************************************',\n//   apiKey: '****************************************'\n// }\n```\n\n### filter() - Remover Campos\n\n```typescript\nimport { filter } from '@ozmap/logger';\n\nconst dados = {\n  usuario: 'admin',\n  senha: 'secret123',\n  email: 'admin@example.com'\n};\n\nconst seguro = filter(dados, ['senha']);\n// {\n//   usuario: 'admin',\n//   email: 'admin@example.com'\n// }\n```\n\n---\n\n## Variáveis de Ambiente\n\n| Variável | Descrição | Valores | Padrão |\n|----------|-----------|---------|--------|\n| `OZLOGGER_LEVEL` | Nível mínimo de log | `quiet`, `error`, `warn`, `audit`, `info`, `debug` | `audit` |\n| `OZLOGGER_OUTPUT` | Formato de saída | `json`, `text` | `json` |\n| `OZLOGGER_COLORS` | Colorização no terminal | `true`, `false` | `false` |\n| `OZLOGGER_DATETIME` | Incluir timestamp | `true`, `false` | `false` |\n| `OZLOGGER_SERVER` | Endereço do servidor HTTP | `[host]:port` | `9898` |\n| `OZLOGGER_HTTP` | Habilitar servidor HTTP | `true`, `false` | `true` |\n\n---\n\n## Exemplos de Uso\n\n----\n\n## Available log methods\nThe available logging methods are presented in hierarchy level order.\n\n - `.debug(...messages: any[])`\n - `.info(...messages: any[])`\n - `.audit(...messages: any[])`\n - `.warn(...messages: any[])`\n - `.error(...messages: any[])`\n\nThere are also timing methods available:\n\n - `.time(id: string)`\n - `.timeEnd(id: string)`\n\n## Usage examples\nHere is a simple code snippet example of using it with typescript:\n\n```typescript\nimport createLogger from '@ozmap/logger';\n\n// Initialize and configure the logging facility\nconst logger = createLogger();\n\n// Example of simple debug log\nlogger.debug(\"Simple test log\");\n```\n\nOr if you are using it with javascript:\n\n```javascript\nconst createLogger = require('@ozmap/logger');\n\n// Initialize and configure the logging facility\nconst logger = createLogger();\n\n// Example of simple debug log\nlogger.debug(\"Simple test log\");\n```\n\nYou can also use it to time operations:\n\n```typescript\nimport createLogger from '@ozmap/logger';\n\n// Initialize and configure the logging facility\nconst logger = createLogger();\n\n// Example of timing an operation\nlogger.time(\"test-operation\");\n\n// ... some code here ...\n\nlogger.timeEnd(\"test-operation\");\n```\n\nBy default, timing logs are output at the `INFO` level, but you can change this by chaining the level method beforehand:\n\n```typescript\nimport createLogger from '@ozmap/logger';\n\n// Initialize and configure the logging facility\nconst logger = createLogger();\n\n// Example of timing an operation with custom log level\nlogger.debug.time(\"test-operation\");\n\n// ... some code here ...\n\nlogger.debug.timeEnd(\"test-operation\");\n```\n\n\n## HTTP server\nThe logger module also starts an HTTP server on port `9898` by default.\nThis server can be used to change the log level at runtime without having to restart your application.\n\nThe server can be disabled by setting the `OZLOGGER_HTTP=\"false\"` environment variable.\nOr passing it as an option when creating the logger itself.\n\n```typescript\nimport createLogger from '@ozmap/logger';\n\n// Initialize and configure the logging facility\nconst logger = createLogger({ noServer: true });\n```\n\n\n## Changing log levels\n\nYou can change log levels by setting the `OZLOGGER_LEVEL` environment variable on your deployment.\n\n```bash\nOZLOGGER_LEVEL=\"debug\"\n```\n\nOr alternatively you can make an HTTP request to the logger's server to change the log level at runtime without restarting your application.\n\n```text\nPOST http://localhost:9898/changeLevel\n{\n    \"level\": \"\u003clog-level\u003e\",\n    \"duration\": \u003cmilliseconds\u003e\n}\n```\n\n```curl\ncurl -L -X POST -H 'Content-Type: application/json' -d '{\"level\":\"\u003clog-level\u003e\",\"duration\":\u003cmilliseconds\u003e}' http://localhost:9898/changeLevel\n```\n\n**IMPORTANT:** If you have disabled the HTTP server, you will not be able to change the log level at runtime.\n\nWhen changing the log level at runtime, you must specify a duration (in milliseconds) for how long the new log level should be active. Afterwards, the log level will revert to the default level set in the environment variable `OZLOGGER_LEVEL` or to 'INFO' if not set.\n\n\n## Logging during development\n\nSince the logger module is primarily designed for production use and performance, it comes with non friendly defaults for development purposes.\n\nOut of the box, the logger will output messages in a JSON format without colors or pretty printing.\n\nIt is recommended for **development only** purposes to set the `OZLOGGER_COLORS=\"true\"` and `OZLOGGER_OUTPUT=\"text\"` environment variables to enable colored and easier to read logs.\n\nAnother option that can be useful during development is to set the `OZLOGGER_DATETIME=\"true\"` environment variable to enable timestamped logs.\n\n\n## Logging during testing\n\nWhen running tests, you can come across situations where the HTTP port `9898` is already in use by another instance of the logger module. Because of this, it is recommended to disable the HTTP server during tests by setting the `OZLOGGER_HTTP=\"false\"` environment variable.\n\nBesides that, if you want to avoid cluttering your test output with log messages, you can set the `OZLOGGER_LEVEL=\"quiet\"` environment variable to suppress all log messages.\n\n---\n\n## Testes (Obrigatório)\n\n**IMPORTANTE:** É obrigatório executar os testes e verificar a cobertura de código antes de enviar qualquer alteração.\n\n### Executando os Testes\n\n```bash\n# Com npm\nnpm test\n\n# Com yarn\nyarn test\n\n# Com pnpm\npnpm test\n\n# Modo watch (desenvolvimento)\nnpm run test:watch\n```\n\n### Cobertura de Código\n\nA cobertura de código é um requisito obrigatório para todas as contribuições. Execute:\n\n```bash\n# Executar testes com cobertura\nnpm test -- --coverage\n\n# Com yarn\nyarn test --coverage\n\n# Com pnpm\npnpm test -- --coverage\n```\n\n### Configuração do Jest\n\nO projeto utiliza Jest com a seguinte configuração:\n\n```javascript\n// jest.config.js\nmodule.exports = {\n    preset: 'ts-jest',\n    testEnvironment: 'node',\n    collectCoverageFrom: [\n        'lib/**/*.ts',\n        '!lib/**/*.d.ts'\n    ],\n    coverageThreshold: {\n        global: {\n            branches: 80,\n            functions: 80,\n            lines: 80,\n            statements: 80\n        }\n    }\n};\n```\n\n### Variáveis de Ambiente para Testes\n\n```bash\n# Recomendado para testes\nOZLOGGER_HTTP=\"false\"    # Desabilita servidor HTTP\nOZLOGGER_LEVEL=\"quiet\"   # Suprime todos os logs\n```\n\n### Estrutura dos Testes\n\n```\ntests/\n├── logger.test.ts       # Testes da classe Logger\n├── logger.perf.test.ts  # Testes de performance\n└── utils.test.ts        # Testes dos utilitários (mask, filter)\n```\n\n### Requisitos para Pull Requests\n\n- [ ] Todos os testes existentes devem passar\n- [ ] Novos recursos devem ter testes correspondentes\n- [ ] Cobertura de código não pode diminuir\n- [ ] Testes devem ser executados com `OZLOGGER_HTTP=false`\n\n---\n\n## Contribuindo\n\n### Pré-requisitos\n\n- Node.js 20+\n- npm, yarn ou pnpm\n\n### Configuração do Ambiente\n\n```bash\n# Clonar repositório\ngit clone https://github.com/ozmap/ozlogger.git\ncd ozlogger\n\n# Instalar dependências\nnpm install  # ou yarn ou pnpm install\n\n# Executar build\nnpm run build\n\n# Executar testes\nnpm test\n```\n\n### Scripts Disponíveis\n\n| Script | Descrição |\n|--------|-----------|\n| `npm run build` | Compila TypeScript |\n| `npm run build:watch` | Compila em modo watch |\n| `npm run test` | Executa testes |\n| `npm run test:watch` | Testes em modo watch |\n| `npm run lint` | Executa linter |\n| `npm run format` | Formata código com Prettier |\n\n### Fluxo de Contribuição\n\n1. Fork o repositório\n2. Crie uma branch (`git checkout -b feature/nova-funcionalidade`)\n3. Faça suas alterações\n4. Execute os testes (`npm test -- --coverage`)\n5. Commit suas mudanças (`git commit -m 'feat: adiciona nova funcionalidade'`)\n6. Push para a branch (`git push origin feature/nova-funcionalidade`)\n7. Abra um Pull Request\n\n---\n\n## Documentação Adicional\n\nPara informações mais detalhadas, consulte:\n\n- [Quick Guide](docs/QUICK-GUIDE.md) - Guia rápido com exemplos práticos\n- [Arquitetura](docs/ARCHITECTURE.md) - Detalhes da arquitetura interna\n- [Análise: Sistema HTTP](docs/ANALYSIS-HTTP-SYSTEM.md) - Análise profunda do servidor HTTP\n- [Análise: Process Hang](docs/ANALYSIS-PROCESS-HANG.md) - Análise técnica do problema de processo pendurado\n- [Melhorias](docs/IMPROVEMENTS.md) - Lista de melhorias planejadas\n- [Problemas Conhecidos](docs/ISSUES.md) - Issues e workarounds\n- [Agents](Agents.md) - Descrição dos agentes/componentes\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozmap%2Fozlogger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fozmap%2Fozlogger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozmap%2Fozlogger/lists"}