iugu_logger 0.10.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9f3b99e1a559a5f178c6b1912682683904d257c4f951f33ea5dce7f61e8c3e0d
+  data.tar.gz: 3eae5a9150343a4a467d422eb87956fe7995a0f83cd0636304559ba767fda055
+SHA512:
+  metadata.gz: 4db9c2d097eb568762a8e931f7d484ca3b294d25a926f84b1031f75ef0bc6d27cf50c466a9d2049cccfe9221396d541608f73f65cade6af3d68f3efc2be56fe0
+  data.tar.gz: a1e4f13b8b04c6be87b5cacf2dbac6c09b1370906b2e83a7427eb3a63197a45033069085d148c78b5b582424b9441021ca22f1a71aedf09661ae0156e353903a

data/LICENSE.md

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 iugu
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,379 @@
+# iugu_logger
+
+> SDK Ruby do iugu Logging Standard (ILS) — schema canônico, PII detection, trace context, registry de eventos, paridade `rails_semantic_logger`. Funciona de Ruby 2.4 (platform) até 3.x (Rails 8).
+
+SDK Ruby que implementa o **iugu Logging Standard (ILS)**: logging estruturado JSON, schema canônico de eventos, detecção de PII e correlação de trace context.
+
+---
+
+## Status: **v0.9.0 — em produção**
+
+Validado em produção em 2026-05-13 com tráfego real. Componentes:
+
+| Componente | Versão | Estado |
+|---|---|---|
+| `IuguLogger.configure` DSL + `Logger.event` core | 0.1 | ✅ |
+| Custom `:note` severity (entre `:info` e `:warn`) | 0.1 | ✅ |
+| `IuguLogger::Pii` — 3-layer scanner + BR regex + SAFE_PATTERNS | 0.2 | ✅ |
+| `IuguLogger::Schema::Validator` — registry, `:off`/`:warn`/`:strict` + Levenshtein | 0.3 | ✅ |
+| `IuguLogger::TraceContext` — OTEL/Datadog/W3C/X-Request-Id chain | 0.3.1 | ✅ |
+| `IuguLogger::TenantContext` — Rack env extractor | 0.3.1 | ✅ |
+| `IuguLogger::Buffer` (thread-local) + `RequestLogger` Rack middleware | 0.4.0 | ✅ |
+| `IuguLogger::JobLogger` — Sidekiq + ActiveJob middlewares | 0.4.1 | ✅ |
+| `IuguLogger::Railtie` — auto-config Rails + Sidekiq + ActionController runtime subscriber | 0.5 → 0.8.1 | ✅ |
+| Install generator + smoke rake task | 0.6.0 | ✅ |
+| PII timing fix (re-read tenant after `@app.call`) | 0.6.3 | ✅ |
+| **Data-completeness-first PII defaults** (`:detect_only` para CPF/CNPJ/phone/email/address) | **0.7.0** | ✅ |
+| **`RequestLogger` enrichment** (`params`, `format`, `status_message`, `rails.*`) | **0.8.0** | ✅ |
+| **CC Luhn check + format/runtime fallbacks** | **0.8.1** | ✅ |
+| **`max_log_size_kb` truncation + conformance runner** | **0.9.0** | ✅ |
+| **Single-line JSON default em todo ambiente** (`IUGU_LOG_PRETTY` ativa pretty) | unreleased | ✅ |
+| **Trace enrichment OTEL-aware** (`source`, `sampled`, `otel` diag, `parent_id` backfill) | unreleased | ✅ |
+| **`service.instance` opt-in** (`emit_service_instance`, default off) | unreleased | ✅ |
+| **Trace auto-correlation em `event()`** (herda do Buffer; fallback OTEL ambiente) | unreleased | ✅ |
+| Conformance suite cross-language passing + v1.0 publish | 1.0 | ⏳ |
+
+**~197 RSpec examples** passing em Ruby **2.4 / 2.7 / 3.2** matrix.
+
+---
+
+## Integração em 3 passos
+
+### 1. Adicionar a gem ao `Gemfile`
+
+```ruby
+gem "iugu_logger", "~> 0.9"
+```
+
+Depois rode `bundle install`. A gem é pública na RubyGems.org — sem `source` customizado, autenticação ou secret de build.
+
+Defina `GIT_SHA` no build/deploy (`service.version` dos eventos): no Dockerfile via `ARG GIT_SHA` + `ENV GIT_SHA=${GIT_SHA}`, ou via env no Deployment.
+
+### 2. Gerar initializer + populate Rack tenant + smoke
+
+```sh
+rails g iugu_logger:install
+bundle exec rake iugu_logger:smoke
+```
+
+Pra popular `iugu.account_id` nos eventos canônicos, adicionar no `ApplicationController` (ou `Api::BaseController`):
+
+```ruby
+include Api::IuguTenantContext  # popula request.env["iugu.current_account_id"] após :authenticate
+```
+
+Exemplo do concern (que vive no app, não no SDK):
+
+```ruby
+# app/controllers/concerns/api/iugu_tenant_context.rb
+module Api
+  module IuguTenantContext
+    extend ActiveSupport::Concern
+    included do
+      before_action :populate_iugu_tenant_context
+    end
+
+    private
+
+    def populate_iugu_tenant_context
+      return if current_account.blank?
+      request.env["iugu.current_account_id"]      = current_account.id
+      request.env["iugu.current_tier"]            = current_account.tier if current_account.respond_to?(:tier)
+    rescue StandardError => e
+      Rails.logger.warn("IuguTenantContext: #{e.class}: #{e.message}")
+    end
+  end
+end
+```
+
+---
+
+## O canonical event (`http.request.completed`) — exemplo real de prod
+
+```jsonc
+{
+  "@timestamp": "2026-05-13T15:03:13.835646Z",
+  "log.level": "info",
+  "event.kind": "event",
+  "event.action": "http.request.completed",
+  "message": "PATCH /api/v1/payments 200 [39ms]",
+
+  "service": {
+    "name": "payments-api",
+    "version": "1db43d1c238229c550a68d44c3be6892fc11d398",  // build SHA
+    "environment": "production"
+    // "instance" (= pod name) é opt-in: por padrão NÃO é emitido, pois o
+    // Alloy já anexa o label `pod_name`. Habilite com
+    // c.emit_service_instance = true em contextos sem coletor (dev/local).
+  },
+
+  "trace": {
+    "id": "6a0492b10000000027ed5c23af8b1ff0",
+    "span_id": "77c72a8787354d51",
+    "parent_id": null,                                       // span do chamador upstream; null = trace nasceu aqui
+    "source": "opentelemetry",                               // opentelemetry | datadog | w3c | request_id
+    "sampled": true                                          // decisão de sampling (quando a origem expõe)
+  },
+
+  "iugu": {
+    "account_id": "1Huj2DcSjtUnVPQbAGqwpR"                   // tenant
+  },
+
+  "request": {
+    "id": "3ba30263-0786-4fa7-ad3a-5a34a5012d69",
+    "method": "PATCH",
+    "path": "/api/v1/payments",
+    "source": "api",
+    "format": "json",                                        // v0.8.0
+    "params": { /* payload completo, Rails filter_parameters aplicado */ }  // v0.8.0
+  },
+
+  "rails": {                                                 // v0.8.0
+    "controller": "Api::V1::PaymentsController",
+    "action": "update",
+    "view_runtime_ms": 0.21,                                 // v0.8.1 (via process_action subscriber)
+    "db_runtime_ms": 4.50                                    // v0.8.1
+  },
+
+  "http": {
+    "status_code": 200,
+    "status_message": "OK",                                  // v0.8.0
+    "duration_ms": 39
+  },
+
+  "pii": {
+    "scanned": true,
+    "detected": ["cnpj", "phone", "email"],                  // detection-only por default
+    "redacted": 0                                            // só CC + credenciais redactam
+  }
+}
+```
+
+**Paridade com `rails_semantic_logger` legacy** (Completed #...) + valor adicionado iugu (`event.action`, `service.version`, `service.instance`, `iugu.account_id`, `pii.detected`, `trace.id` correlation).
+
+---
+
+## API
+
+### Emissão direta de evento
+
+```ruby
+IuguLogger.event("fraud.feedzai.payment.created",
+                 message: "feedzai payment payload sent",
+                 iugu:    { account_id: account.id, tier: account.tier },
+                 fraud:   { feedzai_environment: "prod", lifecycle_id: "PIXUGU:..." })
+```
+
+**Trace auto-correlation:** eventos emitidos durante um request/job herdam
+automaticamente o `trace.*` (mesmo `trace_id` do `http.request.completed` /
+log consolidado), sem você passar nada. A resolução é Buffer (preenchido pelo
+RequestLogger) → span ambiente do OpenTelemetry/Datadog (cobre jobs/scripts).
+Passar `trace:` explicitamente sobrescreve. Fora de qualquer contexto de
+trace, o bloco é omitido.
+
+### Severity (incluindo `:note` custom)
+
+```ruby
+IuguLogger.event("pix.out.timeout",
+                 severity: :error,
+                 message:  "JDPI timeout after 30s",
+                 pix:      { end_to_end_id: e2e })
+```
+
+Levels: `:trace`, `:debug`, `:info`, `:note` (custom — entre info e warn), `:warn`, `:error`, `:fatal`.
+
+### Buffer thread-local (in-app logs durante request)
+
+```ruby
+IuguLogger::Buffer.current.push(severity: :info, message: "validating pix request")
+IuguLogger::Buffer.current.push(severity: :note, message: "pix accepted by jdpi")
+```
+
+`RequestLogger` drena no fim da request → `logs: [...]` no evento `http.request.completed`. **1 log/request consolidado**.
+
+### ActiveJob
+
+```ruby
+class ApplicationJob < ActiveJob::Base
+  include IuguLogger::JobLogger::ActiveJob
+end
+```
+
+Cada execução de job emite `activejob.job.completed` (ou `.failed`) com `request: { id: job_id, source: "activejob" }`, `labels: { job_class, queue, attempt }`, `duration_ms`, `logs: [...]`.
+
+### Sidekiq
+
+Auto-registrado pelo Railtie quando Sidekiq é detectado no boot. Standalone:
+
+```ruby
+Sidekiq.configure_server do |config|
+  config.server_middleware { |chain| chain.add IuguLogger::JobLogger::Sidekiq }
+end
+```
+
+---
+
+## Configuração
+
+### Override via `IuguLogger.configure`
+
+```ruby
+IuguLogger.configure do |c|
+  c.service_name        = "payments-api"   # auto-derived em Rails
+  c.service_version     = ENV["GIT_SHA"] || "0.0.0"
+  c.service_environment = Rails.env
+
+  c.format = %w[1 true yes].include?(ENV["IUGU_LOG_PRETTY"].to_s.downcase) ? :pretty : :json
+  # ↑ single-line JSON em todo ambiente por padrão; IUGU_LOG_PRETTY=true ativa pretty local
+
+  c.event_action_validator = :warn              # :off | :warn | :strict
+  c.event_action_registry  = JSON.parse(File.read("dist/registry.json"))
+
+  # service.instance (= HOSTNAME/POD_NAME) — OFF por padrão. Em K8s + Alloy o
+  # label `pod_name` já cobre isso; habilite só em dev/local ou fora do K8s.
+  # c.emit_service_instance = true
+end
+```
+
+### Schema validator
+
+| Mode | Comportamento |
+|---|---|
+| `:off` (default sem registry) | Sem validation, aceita qualquer `event.action` |
+| `:warn` | Anota `labels.schema_warning: "unknown_event_action"`, emite normal |
+| `:strict` | Raise `IuguLogger::UnknownEventAction` (sugestões typo via Levenshtein) ou `SchemaViolation` (campos required ausentes) |
+
+### PII strategies — data-completeness-first (v0.7+)
+
+| Tipo | Default | Comportamento |
+|---|---|---|
+| `cpf`, `cnpj`, `phone`, `email`, `address` | `:detect_only` | Conteúdo preservado, `pii.detected` populado |
+| `cc` (cartão) — **com validação Luhn** (v0.8.1) | `:last4` | `**** **** **** 1234` (PCI-DSS) |
+| `aws_key`, `bearer`, `url_with_creds` | `:full_redact` | `[AWS_KEY_REDACTED]` (credenciais — nunca user data) |
+
+**`account_id` 32-hex** (ILS-002) e **schema canonical paths** (`trace.*`, `request.id`, `service.*`) — `SAFE_KEY_PATHS` skipa scan inteiramente.
+
+**Override per-app** (apps que precisam stricter, ex: external log export):
+
+```ruby
+c.pii_redaction = IuguLogger::Pii::DEFAULT_STRATEGIES.merge(
+  cpf:   :full_redact,
+  email: :full_redact
+)
+```
+
+### Trace context (chain de fallback)
+
+`IuguLogger::TraceContext.extract(rack_env: env)` resolve a origem nesta ordem (primeira não-nil vence):
+
+1. `OpenTelemetry::Trace.current_span` (Ruby ≥ 2.6 com otel-api) → `source: "opentelemetry"`
+2. `Datadog::Tracing.active_trace` (ddtrace) → `source: "datadog"`
+3. W3C `traceparent` header → `source: "w3c"`
+4. iugu legacy `X-Request-Id` / Rails `action_dispatch.request_id` → `source: "request_id"` (correlação só, `span_id` zerado)
+5. `nil` — Logger emite sem o bloco `trace.*`
+
+O bloco `trace` resultante carrega:
+
+| Campo | Descrição |
+|---|---|
+| `id` | trace ID 32-hex — vem direto do OTEL quando ativo (o nome ECS já carrega o identificador OpenTelemetry) |
+| `span_id` | span ID 16-hex do span local |
+| `parent_id` | span do chamador upstream, backfilled do `traceparent` recebido quando o trace foi continuado. **Presente = trace veio de outro serviço; `null` = trace nasceu nesta chamada** |
+| `source` | origem do contexto: `opentelemetry` / `datadog` / `w3c` / `request_id` |
+| `sampled` | decisão de sampling (bit das trace-flags), quando a origem expõe. `false` = trace não será exportado ao backend, mas o log ainda correlaciona pelo `id` |
+| `otel` | diagnóstico `"not_configured"` quando o SDK do OpenTelemetry está no bundle mas nunca foi inicializado (`OpenTelemetry::SDK.configure` não rodou). Ausente quando OTEL está ativo ou não está no bundle |
+
+---
+
+## Migração `Rails.logger.X` → `IuguLogger.event`
+
+### Regra de coexistência (spec §10)
+
+**Não remover `Rails.logger.X` antes da gem v0.8+ estar validada em produção e o evento canônico carregar todos os dados.** Pattern de migração rolling:
+
+```ruby
+def submit_payment(params:)
+  enriched = enrich(params)
+
+  # Legacy — mantido durante rolling, ops/suporte/fraude dependem
+  Rails.logger.info("Payload enviado para a feedzai", enriched)
+
+  # Canônico — schema iugu, eventualmente substitui o legacy
+  IuguLogger.event("fraud.feedzai.payment.created",
+                   message: "Payload enviado para a feedzai",
+                   fraud:   { feedzai_environment:, payload: enriched })
+
+  post_payment(enriched)
+end
+```
+
+Após validação em prod (~dias), follow-up PR remove a linha legacy.
+
+### Exemplos antes/depois
+
+**Antes (string interpolation — antipattern):**
+
+```ruby
+Rails.logger.error("Erro processando #{user.id}: #{e.message}")
+```
+
+**Depois (kv-args + schema):**
+
+```ruby
+IuguLogger.event("user.processing.failed",
+                 severity: :error,
+                 iugu:     { user_id: user.id },
+                 error:    { type: e.class.name, message: e.message })
+```
+
+---
+
+## Decisões aplicadas
+
+| ID | Decisão | Implementação |
+|---|---|---|
+| ILS-002 | `iugu.account_id` 32-hex preservado | `Pii::SAFE_PATTERNS` + `SAFE_KEY_PATHS` |
+| ILS-003 | Email `:detect_only` (deferido — agora **generalizado** em v0.7) | `Pii::DEFAULT_STRATEGIES` |
+| §13.7 | Ruby 2.4 first-class | `gemspec.required_ruby_version >= 2.4` + CI matrix |
+| **v0.7** | **Data-completeness-first** — PII detection-only por default | `Pii::DEFAULT_STRATEGIES` |
+| **v0.8.0** | **`RequestLogger` enrichment** pra paridade com `rails_semantic_logger` | `request_logger.rb` |
+| **v0.8.1** | **CC Luhn check** previne CNPJ false-positive | `Pii::Scanner#luhn_valid?` |
+| **v0.9.0** | **`max_log_size_kb` truncation + conformance runner** | `Configuration#max_log_size_kb` + `spec/conformance/` |
+| **unreleased** | **Single-line JSON default** em todo ambiente (Loki/Alloy: 1 evento/linha; pretty via `IUGU_LOG_PRETTY`) | `Configuration#format` |
+| **unreleased** | **Trace context OTEL-aware** — `source`/`sampled`/`otel` diag + `parent_id` backfill do `traceparent` recebido | `trace_context.rb` |
+| **unreleased** | **`service.instance` opt-in** — evita duplicar o label `pod_name` que o Alloy já anexa | `Configuration#emit_service_instance` |
+| **unreleased** | **Trace auto-correlation** — `IuguLogger.event` herda o `trace.*` do request/job (Buffer > OTEL ambiente); `trace:` explícito vence | `Logger#inject_trace_context` |
+
+---
+
+## Distribuição
+
+Publicada na [RubyGems.org](https://rubygems.org/gems/iugu_logger) — `gem "iugu_logger"`, sem autenticação. Versionamento segue [SemVer](https://semver.org) e o `CHANGELOG.md` acompanha cada release.
+
+---
+
+## Desenvolvimento
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+CI valida matriz Ruby 2.4 + 2.7 + 3.2 em todo PR.
+
+---
+
+## Compatibilidade
+
+- Ruby >= 2.4 (cobre platform Rails 4.2 até modernos)
+- Rails opcional (Railtie auto-config quando detectado)
+- ActionController::API e ActionController::Base (subscriber pra `process_action.action_controller` v0.8.1)
+- Sidekiq opcional (auto-registra)
+- ActiveJob opcional (mixin opt-in)
+- OpenTelemetry opcional (chain fallback)
+
+---
+
+## Ownership
+
+Mantido pela Engenharia de Plataforma da iugu — `eng-plataforma@iugu.com`.

data/lib/generators/iugu_logger/install/install_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module IuguLogger
+  module Generators
+    # Run via:
+    #   rails g iugu_logger:install
+    #
+    # Creates `config/initializers/iugu_logger.rb` with sensible defaults.
+    # Idempotent — re-running asks before overwriting.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Generate config/initializers/iugu_logger.rb with iugu Logging Standard defaults'
+
+      def create_initializer
+        template 'iugu_logger.rb.tt', 'config/initializers/iugu_logger.rb'
+      end
+
+      def post_install_summary
+        say "\n  iugu_logger #{IuguLogger::VERSION} initializer installed.", :green
+        say '  Run `bundle exec rake iugu_logger:smoke` to validate the setup.', :green
+      end
+
+      private
+
+      # Best-effort default service name from the Rails app class.
+      # Same heuristic as IuguLogger::Railtie#derive_service_name (kept in sync).
+      def default_service_name
+        klass = Rails.application.class.name.to_s
+        return 'rails-app' if klass.empty?
+
+        first = klass.split('::').first
+        first.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+             .downcase
+             .tr('_', '-')
+      rescue StandardError
+        'rails-app'
+      end
+    end
+  end
+end

data/lib/generators/iugu_logger/install/templates/iugu_logger.rb.tt

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# iugu Logging Standard (ILS) — Ruby SDK setup.
+#
+# Generated by `rails g iugu_logger:install`. Edit freely; sensible defaults
+# below cover the canonical case. After changes, validate with:
+#
+#     bundle exec rake iugu_logger:smoke
+
+IuguLogger.configure do |c|
+  c.service_name        = '<%= default_service_name %>'
+  # service_version: short git SHA from build/deploy time. Set GIT_SHA at
+  # build/deploy (Dockerfile ARG/ENV or K8s downward API).
+  c.service_version     = ENV['GIT_SHA'] || '0.0.0'
+  c.service_environment = Rails.env
+
+  # service.instance (= HOSTNAME/POD_NAME) is OFF by default: in the K8s +
+  # Alloy pipeline the `pod_name` label already carries it, so emitting it
+  # here would duplicate it on every line. Enable for local/non-K8s contexts
+  # where no collector enriches the log:
+  # c.emit_service_instance = true
+
+  # Single-line JSON by default in EVERY environment (Loki/Alloy ingestion
+  # expects exactly one event per line). Opt into multi-line pretty output
+  # locally for legibility with IUGU_LOG_PRETTY=true.
+  c.format = %w[1 true yes].include?(ENV['IUGU_LOG_PRETTY'].to_s.downcase) ? :pretty : :json
+
+  # event.action validator:
+  #   :off    — no validation (default if no registry loaded)
+  #   :warn   — annotates labels.schema_warning, never blocks emit
+  #   :strict — raises UnknownEventAction / SchemaViolation
+  # Move to :strict once `event_action_registry` is loaded and event coverage
+  # is complete.
+  c.event_action_validator = :warn
+
+  # PII strategies (since v0.7 — data-completeness-first):
+  #   - cpf/cnpj/phone/email/address  → :detect_only
+  #     PII is DETECTED (audit-queryable via `pii.detected`) but not
+  #     removed from the log. Ops, support, fraud, and ML pipelines
+  #     depend on the raw values.
+  #   - cc                            → :last4 (PCI-DSS hard rule)
+  #   - aws_key/bearer/url_with_creds → :full_redact (credentials)
+  # iugu.account_id 32-hex is preserved unconditionally (ILS-002 SAFE_PATTERN).
+  #
+  # For apps that need stricter redaction (e.g. external log export
+  # targets), override per-type:
+  #
+  #   c.pii_redaction = IuguLogger::Pii::DEFAULT_STRATEGIES.merge(
+  #     cpf:   :full_redact,
+  #     email: :full_redact
+  #   )
+end