feat: initial structure stable release lib observability

[gandalf-at-lerian]

Summary

• promotes the current develop branch to main for the first stable lib-observability release
• includes the migrated observability packages, logging/telemetry middleware, CI/lint/security workflow standardization, and unit coverage gate above 80%
• keeps main as the stable release branch now that develop has passed the release-quality checks

Validation

• PR chore(ci): prepare stable release gates #4 CI/lint/workflow standardization merged to develop
• PR feat: add logging middleware #5 logging middleware and observability helpers merged to develop
• PR test: raise lib-observability unit coverage #6 unit coverage raised to 84.6% and merged to develop
• current develop branch is ahead of main with the stable release set

Requested by: @qnen

[coderabbitai]

<review_stack_artifact>

</review_stack_artifact>

[lerian-studio]

🔍 PR Validation Summary

✅ PR Mergeable — no blocking failures

Check	Status	Blocking
Source Branch	✅ success	yes
PR Title	✅ success	yes
PR Description	✅ success	yes
PR Size	✅ success	no
Auto Labels	✅ success	no
PR Metadata	✅ success	no

---

_{🔍 View workflow run}

[lerian-studio]

🔒 Security Scan Results — lib-observability

✅ PR Mergeable — no blocking findings

Stage	Status	Blocking?
Filesystem Scan	✅ Clean	—
Docker Image Scan	➖ Skipped	—
Docker Hub Health Score	➖ Skipped	—
Pre-release Version Check	✅ Clean	—

Trivy

Filesystem Scan

✅ No vulnerabilities or secrets found.

---

Pre-release Version Check

✅ No unstable version pins found.

---

_{🔍 View full scan logs}

[lerian-studio]

📊 Unit Test Coverage Report: lib-observability

Metric	Value
Overall Coverage	84.2% ✅ PASS
Threshold	80%

Coverage by Package

Package	Coverage
github.com/LerianStudio/lib-observability/assert	97.9%
github.com/LerianStudio/lib-observability/constants	83.3%
github.com/LerianStudio/lib-observability/log	94.9%
github.com/LerianStudio/lib-observability/metrics	91.4%
github.com/LerianStudio/lib-observability/middleware	67.6%
github.com/LerianStudio/lib-observability/redaction	95.8%
github.com/LerianStudio/lib-observability/runtime	80.4%
github.com/LerianStudio/lib-observability/tracing	84.9%
github.com/LerianStudio/lib-observability/zap	96.0%
github.com/LerianStudio/lib-observability	91.1%

---

Generated by Go PR Analysis workflow

[coderabbitai]

Actionable comments posted: 18

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.releaserc.yml:
- Around line 11-20: YAML flow mappings in .releaserc.yml have extra spaces
inside braces causing YAMLlint `braces` errors; update each mapping (examples:
the objects currently written as { type: "feat", release: "minor" }, { type:
"perf", release: "minor" }, ... and the breaking entry { breaking: true,
release: "major" }) to remove the spaces immediately after '{' and before '}' so
they become {type: "feat", release: "minor"} etc., and apply the same change to
the entry around the 33rd line.

In `@CLAUDE.md`:
- Around line 17-18: Update the stale table entry that declares "Streaming
telemetry | `streaming/` package" and the related rule "lib-commons dependency |
**NEVER import lib-commons**": replace the streaming row to indicate streaming
has been moved back into lib-commons (e.g., "Streaming telemetry | now in
lib-commons") and revise the lib-commons guidance to reflect that importing
lib-commons is allowed for streaming-related code or clarify permitted uses
(remove the absolute "NEVER import lib-commons" wording); ensure the table
entries and surrounding sentence(s) referencing `streaming/` and `lib-commons`
are consistent with the current release.

In `@constants/headers.go`:
- Around line 4-9: HeaderTraceparent is incorrectly set to the PascalCase value
and duplicates HeaderTraceparentPascal; change the value of the constant
HeaderTraceparent to the canonical lowercase "traceparent" (leave
HeaderTraceparentPascal as "Traceparent" and keep HeaderTracestatePascal
unchanged) so exact-key header propagation can rely on distinct lowercase and
PascalCase variants.

In `@go.mod`:
- Line 3: The go directive in go.mod is pinned to "go 1.25.9" which has known
security advisories; update that directive to "go 1.25.10" to pick up the fixes
(replace the existing go 1.25.9 token in go.mod with go 1.25.10) and re-run go
mod tidy/build to ensure modules are compatible.

In `@middleware/logging_obfuscation.go`:
- Around line 12-24: The current getBodyObfuscatedString falls back to returning
string(bodyBytes) for unknown content types, which can leak PII; change the
fallback to return a safe redacted placeholder (e.g., "[REDACTED]") instead of
the raw body, and ensure the same pattern is applied to any other raw-body
fallbacks in this file (replace raw returns in the URL-encoded/JSON error paths
and the other similar function) so only handleJSONBody, handleURLEncodedBody,
and handleMultipartBody return content-derived values while all
unsupported/error paths return the placeholder.

In `@middleware/telemetry_route_test.go`:
- Around line 19-27: The test calls t.Parallel() but mutates global
OpenTelemetry tracer provider via setupTestTracer, otel.SetTracerProvider and
otel.GetTracerProvider which can cause flakes; remove t.Parallel() from the test
(or scope the tracer mutation to a subtest that is not parallel) so the test
runs serially while it sets the global tracer, keep the existing defer restoring
otel.SetTracerProvider(oldTP) and tp.Shutdown to ensure cleanup, and reference
the functions setupTestTracer, otel.SetTracerProvider, and
otel.GetTracerProvider when locating the change.

In `@middleware/telemetry.go`:
- Line 99: The code currently ends the same tracing span in two places (defer
span.End() inside WithTelemetry/WithTelemetryInterceptor and again inside
EndTracingSpans/EndTracingSpansInterceptor), which can double-end spans; pick a
single owner and remove the duplicate calls—e.g., remove the deferred span.End()
invocations in WithTelemetry and WithTelemetryInterceptor and let
EndTracingSpans/EndTracingSpansInterceptor be the sole place that calls
span.End(), ensuring each span is started in
WithTelemetry/WithTelemetryInterceptor and ended exactly once in the
EndTracingSpans/EndTracingSpansInterceptor helpers.

In `@README.md`:
- Around line 7-13: The README headings and examples reference package paths
"opentelemetry" / "opentelemetry/metrics" but the repo exposes modules as
"tracing" and "metrics"; update the section headings and any import examples to
use "tracing" (for the OpenTelemetry bootstrap, tracer helpers and functions
like NewTelemetry(cfg) and ShutdownTelemetry()) and "metrics" (for
MetricsFactory, NewNopFactory and the fluent API), and search/replace any other
occurrences to ensure docs match actual module paths so import statements and
symbols resolve correctly.

In `@runtime/error_reporter.go`:
- Around line 98-133: The call to reporter.CaptureException inside
reportPanicToErrorService must be made best-effort so a panic inside the error
reporter cannot re-panic the recovery path; wrap the CaptureException invocation
in a local guarded call (e.g., an anonymous function) that defers a recover()
and swallows or logs any panic from CaptureException so it cannot propagate to
KeepRunning; retain existing logic around GetErrorReporter, toPanicError and
IsProductionMode and ensure any panic from the reporter is handled locally and
does not escape reportPanicToErrorService.

In `@runtime/helpers_test.go`:
- Around line 30-42: The testLogger.Log currently marks panicLogged for every
call because it ignores the log.Level parameter; change the signature to capture
the level (e.g., lvl log.Level) and only set panicLogged.Store(true) when the
level indicates a panic (e.g., lvl == log.Panic) or when the message clearly
indicates a panic if your test uses message-based detection; keep the rest of
the behavior (appending to errorCalls, setting lastMessage, and signalling via
logged) unchanged so only real panic-level logs satisfy panic assertions.

In `@runtime/recover.go`:
- Around line 155-178: The panic logger replaces caller contexts with
context.Background(); update logPanicWithStack to accept a context.Context
parameter (e.g., change signature to logPanicWithStack(ctx context.Context,
logger Logger, name string, panicValue any, stack []byte) and use that ctx in
logger.Log calls), update all callers to pass their existing ctx, and leave
context.Background() only where there truly is no caller context; ensure
references to IsProductionMode, redactedPanicMsg and Logger remain unchanged and
that non-context callers still compile by explicitly passing
context.Background().

In `@runtime/tracing.go`:
- Around line 104-107: The code calls trace.SpanFromContext(ctx) without
checking ctx for nil, which can panic; update the guard in the function that
contains span := trace.SpanFromContext(ctx) to first check ctx != nil (or use a
nil-safe helper) and return early if nil before calling trace.SpanFromContext or
span.IsRecording(), so the nil context path is handled safely and avoids panics
in the panic-recovery path.

In `@system.go`:
- Around line 19-59: The collectors (CPU and memory) currently log read errors
but still call RecordSystemCPUUsage/RecordSystemMemUsage with a zero value,
producing misleading telemetry; update both functions (the CPU collection code
that sets percentageCPU from out and GetMemUsage which uses mem.VirtualMemory
and percentageMem) to only call factory.RecordSystemCPUUsage or
factory.RecordSystemMemUsage when the underlying read succeeded (i.e., err ==
nil) — keep the existing error logs and the factory-nil checks, but skip the
metric recording entirely on read error so you don't record a 0 value.

In `@tracing/otel.go`:
- Around line 102-104: normalizeEndpointEnvVars currently mutates process-wide
OTEL env vars via os.Setenv during tracer initialization; change it to be pure:
remove any os.Setenv calls and instead accept the current cfg (or return the
computed endpoint and headers) so normalizeEndpointEnvVars/normalizeEndpoint
compute and return normalized values which the caller then assigns into the
local config used by the tracer (e.g., update the config struct passed into
normalizeEndpoint(&cfg) and the caller of normalizeEndpointEnvVars to set cfg.
Ensure no global os.Setenv is used anywhere in tracing/otel.go (remove or
refactor any os.Setenv in lines around normalizeEndpointEnvVars and 163-175) and
update any tests that assumed env mutation to use the returned config values.
- Around line 562-569: The code builds statusMsg using sanitizeSpanMessage but
concatenates the raw message variable and then passes the original err into
span.RecordError, which can leak control characters/sensitive data; update this
block so you sanitize the full status payload (sanitize the message string
before concatenation or sanitize the combined statusMsg via sanitizeSpanMessage)
and create/record a sanitized error payload to pass into span.RecordError (e.g.,
construct a new error or error wrapper whose Error() returns the sanitized
statusMsg) so both span.SetStatus and span.RecordError use the same sanitized
text (touch symbols: sanitizeSpanMessage, message, statusMsg, span.SetStatus,
span.RecordError, err).
- Around line 154-156: The code currently unconditionally sets
cfg.InsecureExporter = true for scheme-less endpoints (bare host:port); instead,
preserve the caller's explicit intent by removing that automatic downgrade: only
set cfg.InsecureExporter to true if the parsed endpoint explicitly uses the
"http" scheme or if cfg.InsecureExporter was already true; do not flip
cfg.InsecureExporter to true when the input is scheme-less—leave it unchanged so
callers can default to secure gRPC. Ensure the change is made where the endpoint
parsing logic sets cfg.InsecureExporter (the block that currently comments "No
scheme — assume insecure (common in k8s internal comms)").

In `@zap/zap.go`:
- Around line 176-193: The Debug/Info/Warn/Error convenience methods call
l.must().Debug/Info/Warn/Error directly and bypass sanitizeConsoleMsg, so
messages can contain control characters; update each method (Debug, Info, Warn,
Error) to sanitize the message first by calling sanitizeConsoleMsg(message) and
then pass the sanitized string to l.must().Debug/Info/Warn/Error (keeping the
original fields...), or alternatively delegate to the protected Log method after
sanitizing to ensure consistent behavior with Log and prevent forged console
lines.
- Around line 109-111: WithGroup currently treats names containing only
whitespace as valid groups; update the function WithGroup to treat
whitespace-only names the same as empty by checking strings.TrimSpace(name) ==
"" and returning l in that case. Add the strings import if missing and apply the
trimmed-name check where the current name == "" check is located to preserve
documented/GoLogger behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 29421f2a-1b2d-4b34-9c7e-fdf98cea549c

📥 Commits

Reviewing files that changed from the base of the PR and between f79ae63 and 8131921.

⛔ Files ignored due to path filters (1)

• go.sum is excluded by !**/*.sum

📒 Files selected for processing (97)

• .github/FUNDING.yml
• .github/dependabot.yml
• .github/labeler.yml
• .github/labels.yml
• .github/pull_request_template.md
• .github/workflows/go-combined-analysis.yml
• .github/workflows/pr-security-scan.yml
• .github/workflows/pr-validation.yml
• .github/workflows/release.yml
• .github/workflows/routine.yml
• .gitignore
• .golangci.yml
• .goreleaser.yml
• .ignorecoverunit
• .releaserc.yml
• CLAUDE.md
• LICENSE
• Makefile
• README.md
• assert/assert.go
• assert/assert_extended_test.go
• assert/assert_test.go
• assert/doc.go
• assert/predicates.go
• assert/predicates_test.go
• constants/doc.go
• constants/headers.go
• constants/log.go
• constants/metadata.go
• constants/obfuscation.go
• constants/opentelemetry.go
• constants/opentelemetry_test.go
• context_helpers.go
• context_tracking_test.go
• go.mod
• log/doc.go
• log/go_logger.go
• log/log.go
• log/log_mock.go
• log/log_test.go
• log/nil.go
• log/nil_test.go
• log/sanitizer.go
• log/sanitizer_test.go
• metrics/account.go
• metrics/builders.go
• metrics/doc.go
• metrics/metrics.go
• metrics/metrics_test.go
• metrics/operation_routes.go
• metrics/system.go
• metrics/transaction.go
• metrics/transaction_routes.go
• middleware/context_span.go
• middleware/helpers.go
• middleware/logging.go
• middleware/logging_obfuscation.go
• middleware/logging_test.go
• middleware/metrics.go
• middleware/telemetry.go
• middleware/telemetry_route_test.go
• middleware/telemetry_test.go
• observability.go
• observability_test.go
• redaction/doc.go
• redaction/sensitive_fields.go
• redaction/sensitive_fields_test.go
• runtime/doc.go
• runtime/error_reporter.go
• runtime/goroutine.go
• runtime/goroutine_test.go
• runtime/helpers_test.go
• runtime/log_mode_link_test.go
• runtime/metrics.go
• runtime/metrics_test.go
• runtime/policy.go
• runtime/policy_test.go
• runtime/recover.go
• runtime/recover_test.go
• runtime/tracing.go
• runtime/tracing_test.go
• scripts/makefile_colors.mk
• scripts/makefile_utils.mk
• system.go
• system_test.go
• tracing/doc.go
• tracing/obfuscation.go
• tracing/obfuscation_test.go
• tracing/otel.go
• tracing/otel_test.go
• tracing/processor.go
• tracing/v2_test.go
• zap/doc.go
• zap/injector.go
• zap/injector_test.go
• zap/zap.go
• zap/zap_test.go

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

system.go (1)

24-27: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Skip CPU metric recording when no sample is returned.

When cpu.Percent returns an empty slice, this path records 0, which can misrepresent collection quality as real telemetry data. Guard len(out)==0 and return after warning instead of emitting a zero datapoint.

Proposed fix

-	var percentageCPU int64 = 0
-	if len(out) > 0 {
-		percentageCPU = int64(out[0])
-	}
+	if len(out) == 0 {
+		logger.Log(ctx, log.LevelWarn, "cpu usage response is empty, skipping CPU usage recording")
+		return
+	}
+	percentageCPU := int64(out[0])

Also applies to: 34-35

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@system.go` around lines 24 - 27, The code currently converts an empty
cpu.Percent result into a misleading zero by setting percentageCPU :=
int64(out[0]) without guarding for no samples; update the cpu sampling blocks
(the one initializing percentageCPU and the analogous block around lines 34-35)
to check if len(out) == 0 and if so log a warning and return/skip recording
instead of emitting a zero datapoint. Locate the cpu.Percent call and the
percentageCPU variable assignment, add the len(out) == 0 guard, and ensure the
function exits early (or skips metric submission) when no sample is returned.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@middleware/logging.go`:
- Around line 251-269: The buildOpts(opts...) call is duplicated; initialize the
options once before the conditional that calls
getValidBodyRequestID/getMetadataID by assigning mid := buildOpts(opts...)
(ensure you don't shadow mid) and use that mid for the debug Log call and later
for logger creation (logger := mid.Logger.With(...)). Remove the later
buildOpts(opts...) invocation so the same mid is reused across the interceptor.

---

Duplicate comments:
In `@system.go`:
- Around line 24-27: The code currently converts an empty cpu.Percent result
into a misleading zero by setting percentageCPU := int64(out[0]) without
guarding for no samples; update the cpu sampling blocks (the one initializing
percentageCPU and the analogous block around lines 34-35) to check if len(out)
== 0 and if so log a warning and return/skip recording instead of emitting a
zero datapoint. Locate the cpu.Percent call and the percentageCPU variable
assignment, add the len(out) == 0 guard, and ensure the function exits early (or
skips metric submission) when no sample is returned.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 06788ec4-63e6-49a5-93d0-dc8ac77c55c6

📥 Commits

Reviewing files that changed from the base of the PR and between 8131921 and 13312f2.

📒 Files selected for processing (19)

• .github/workflows/go-combined-analysis.yml
• .releaserc.yml
• CLAUDE.md
• README.md
• constants/headers.go
• go.mod
• middleware/logging.go
• middleware/logging_obfuscation.go
• middleware/telemetry.go
• middleware/telemetry_route_test.go
• runtime/error_reporter.go
• runtime/helpers_test.go
• runtime/recover.go
• runtime/recover_test.go
• runtime/tracing.go
• system.go
• tracing/otel.go
• tracing/otel_test.go
• zap/zap.go