Skip to content

refactor(platform): migrate tracer to lib-commons v4 and harden observability #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fredcamaral wants to merge 15 commits into
base: develop
Choose a base branch
from
Open

refactor(platform): migrate tracer to lib-commons v4 and harden observability #58

Show file tree
Hide file tree
Changes from 13 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
4332910
chore(deps): upgrade auth and commons libraries
fredcamaral Mar 11, 2026
db36c91
refactor(core): migrate to native lib-commons v4 APIs
fredcamaral Mar 11, 2026
ec8e1ea
docs(rules): update lib-commons examples to v4
fredcamaral Mar 11, 2026
1918cf8
refactor(logging): centralize trace field helpers
fredcamaral Mar 11, 2026
f7699ea
fix(postgres): propagate request context and harden startup checks
fredcamaral Mar 11, 2026
1167e4f
fix(observability): sanitize telemetry and harden auth metrics paths
fredcamaral Mar 11, 2026
b964b98
fix(observability): surface auth metric recording failures
fredcamaral Mar 11, 2026
130e5d0
test(http): cover missing rule and logging edge cases
fredcamaral Mar 11, 2026
fcabfba
fix(postgres): reject nil contexts when resolving db handles
fredcamaral Mar 11, 2026
d50da51
fix(ci): unblock build and security scan jobs
fredcamaral Mar 11, 2026
19a4bb1
fix(internal): address CodeRabbit safety feedback
fredcamaral Mar 11, 2026
ea4a48f
fix(observability): preserve rollback context and panic details
fredcamaral Mar 11, 2026
37cdcd4
fix(resilience): wrap original error on panic in circuit breaker
fredcamaral Mar 11, 2026
78bea75
refactor(resilience): extract panic recovery logic to new function
fredcamaral Mar 11, 2026
573c63c
style: remove unnecessary blank lines and trailing whitespace
fredcamaral Mar 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/code-quality.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ jobs:
- name: Set up Go
uses: actions/setup-go@v6
with:
go-version: '1.25'
go-version: '1.25.7'

- name: Install golangci-lint
run: |
Expand All @@ -35,7 +35,7 @@ jobs:
- name: Set up Go
uses: actions/setup-go@v6
with:
go-version: '1.25'
go-version: '1.25.7'

- name: Run unit tests
run: go test -race ./...
Expand All @@ -49,7 +49,7 @@ jobs:
- name: Set up Go
uses: actions/setup-go@v6
with:
go-version: '1.25'
go-version: '1.25.7'

- name: Run integration tests
run: make test-integration
Expand All @@ -63,7 +63,7 @@ jobs:
- name: Set up Go
uses: actions/setup-go@v6
with:
go-version: '1.25'
go-version: '1.25.7'

- name: Run tests 3 times
run: |
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/go-combined-analysis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ jobs:
with:
runner_type: "blacksmith-4vcpu-ubuntu-2404"
app_name_prefix: "tracer"
go_version: "1.25"
go_version: "1.25.7"
golangci_lint_version: "v2.7.2"
golangci_lint_args: "--timeout=5m"
coverage_threshold: 85
Expand Down
3 changes: 1 addition & 2 deletions Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ FROM golang:1.26-alpine3.22 AS builder
# Pin package versions for reproducible builds (Alpine 3.22)
ARG CA_CERTIFICATES_VERSION=20250911-r0
ARG GIT_VERSION=2.49.1-r0
ARG TZDATA_VERSION=2025c-r0
ARG TZDATA_VERSION=2026a-r0

WORKDIR /app

Expand Down Expand Up @@ -39,4 +39,3 @@ COPY --from=builder /tracer/migrations /app/migrations
EXPOSE 8080 7001

ENTRYPOINT ["/app/tracer"]

4 changes: 2 additions & 2 deletions docs/CODING_STANDARDS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,7 @@ func (a *Adapter) Method(ctx context.Context) error {
// 2. Enrich logger with trace context (now span exists!)
logger = logging.WithTrace(ctx, logger)

logger.Info("operation started") // ← Includes trace_id and span_id
logger.Log(ctx, libLog.LevelInfo, "operation started") // ← Includes trace.id and span.id
return nil
}

Expand All @@ -253,7 +253,7 @@ func (a *Adapter) Method(ctx context.Context) error {
ctx, span := tracer.Start(ctx, "operation")
defer span.End()

logger.Info("operation started") // ← Missing trace_id and span_id!
logger.Log(ctx, libLog.LevelInfo, "operation started") // ← Missing trace.id and span.id!
return nil
}
```
Expand Down
48 changes: 24 additions & 24 deletions docs/PROJECT_RULES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -921,9 +921,9 @@ import (
"database/sql"

// External dependencies
libCommons "github.com/LerianStudio/lib-commons/v2/commons"
libLog "github.com/LerianStudio/lib-commons/v2/commons/log"
libOpentelemetry "github.com/LerianStudio/lib-commons/v2/commons/opentelemetry"
libCommons "github.com/LerianStudio/lib-commons/v4/commons"
libLog "github.com/LerianStudio/lib-commons/v4/commons/log"
libOpentelemetry "github.com/LerianStudio/lib-commons/v4/commons/opentelemetry"
"github.com/google/uuid"

// Internal packages
Expand Down Expand Up @@ -1319,7 +1319,7 @@ libHTTP.WithError(c, err)

```go
import (
libHTTP "github.com/LerianStudio/lib-commons/v2/commons/net/http"
libHTTP "github.com/LerianStudio/lib-commons/v4/commons/net/http"
"github.com/gofiber/fiber/v2"
)

Expand Down Expand Up @@ -1578,7 +1578,7 @@ Tracer MVP uses single-tenant deployment with API Key authentication only.
import (
"crypto/subtle"

libHTTP "github.com/LerianStudio/lib-commons/v2/commons/net/http"
libHTTP "github.com/LerianStudio/lib-commons/v4/commons/net/http"
"github.com/gofiber/fiber/v2"
)

Expand Down Expand Up @@ -2896,7 +2896,7 @@ func NewRouter(lg libLog.Logger, tl *libOpentelemetry.Telemetry, ...) *fiber.App

### Overview

All logging in this project **MUST** use structured logging with `WithFields` instead of string interpolation. This ensures logs are searchable, indexable, and consistent across all observability tools.
All logging in this project **MUST** use structured logging with `logger.With(...).Log(...)` instead of string interpolation. This ensures logs are searchable, indexable, and consistent across all observability tools.

### Log Field Naming Convention (OpenTelemetry Semantic Conventions)

Expand Down Expand Up @@ -2926,22 +2926,22 @@ package logging
import (
"context"

libLog "github.com/LerianStudio/lib-commons/v2/commons/log"
libLog "github.com/LerianStudio/lib-commons/v4/commons/log"
"go.opentelemetry.io/otel/trace"
)

// WithTrace enriches a logger with trace context (trace.id and span.id).
// Returns the original logger if no valid span is found in context.
func WithTrace(ctx context.Context, logger libLog.Logger) libLog.Logger {
span := trace.SpanFromContext(ctx)
if span.SpanContext().IsValid() {
return logger.WithFields(
"trace.id", span.SpanContext().TraceID().String(),
"span.id", span.SpanContext().SpanID().String(),
)
if !span.SpanContext().IsValid() {
return logger
}

return logger
return logger.With(
libLog.String("trace.id", span.SpanContext().TraceID().String()),
libLog.String("span.id", span.SpanContext().SpanID().String()),
)
}
```

Expand All @@ -2961,19 +2961,19 @@ func (h *Handler) CreateRule(c *fiber.Ctx) error {
logger = logging.WithTrace(ctx, logger)

// Log operation start with structured fields
logger.WithFields(
"operation", "handler.rule.create",
"rule.name", input.Name,
).Info("Creating rule")
logger.With(
libLog.String("operation", "handler.rule.create"),
libLog.String("rule.name", input.Name),
).Log(ctx, libLog.LevelInfo, "Creating rule")

// ... business logic ...

// Log success with structured fields
logger.WithFields(
"operation", "handler.rule.create",
"rule.id", result.ID.String(),
"rule.name", result.Name,
).Info("Rule created successfully")
logger.With(
libLog.String("operation", "handler.rule.create"),
libLog.String("rule.id", result.ID.String()),
libLog.String("rule.name", result.Name),
).Log(ctx, libLog.LevelInfo, "Rule created successfully")

return libHTTP.Created(c, result)
}
Expand Down Expand Up @@ -3049,8 +3049,8 @@ logger.WithFields("operation", "handler.rule.create").Info("...") // Missing Wi

```go
import (
libCommons "github.com/LerianStudio/lib-commons/v2/commons"
libOtel "github.com/LerianStudio/lib-commons/v2/commons/opentelemetry"
libCommons "github.com/LerianStudio/lib-commons/v4/commons"
libOtel "github.com/LerianStudio/lib-commons/v4/commons/opentelemetry"
"go.opentelemetry.io/otel/trace" // OK: Only for trace.Span type
)

Expand Down
104 changes: 52 additions & 52 deletions go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
module tracer

go 1.25.6
go 1.25.7

require (
github.com/DATA-DOG/go-sqlmock v1.5.2
github.com/LerianStudio/lib-auth/v2 v2.4.0
github.com/LerianStudio/lib-commons/v2 v2.9.1
github.com/LerianStudio/lib-auth/v2 v2.5.0-beta.7
github.com/LerianStudio/lib-commons/v4 v4.0.0
github.com/Masterminds/squirrel v1.5.4
github.com/cucumber/godog v0.15.1
github.com/go-playground/locales v0.14.1
Expand All @@ -24,20 +24,20 @@ require (
github.com/stretchr/testify v1.11.1
github.com/swaggo/fiber-swagger v1.3.0
github.com/swaggo/swag v1.16.6
github.com/testcontainers/testcontainers-go v0.40.0
github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0
go.opentelemetry.io/otel v1.40.0
go.opentelemetry.io/otel/sdk v1.40.0
go.opentelemetry.io/otel/sdk/metric v1.40.0
go.opentelemetry.io/otel/trace v1.40.0
github.com/testcontainers/testcontainers-go v0.41.0
github.com/testcontainers/testcontainers-go/modules/postgres v0.41.0
go.opentelemetry.io/otel v1.42.0
go.opentelemetry.io/otel/sdk v1.42.0
go.opentelemetry.io/otel/sdk/metric v1.42.0
go.opentelemetry.io/otel/trace v1.42.0
go.uber.org/mock v0.6.0
golang.org/x/text v0.34.0
golang.org/x/text v0.35.0
)

require (
cel.dev/expr v0.25.1 // indirect
dario.cat/mergo v1.0.2 // indirect
github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 // indirect
github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
github.com/KyleBanks/depth v1.2.1 // indirect
github.com/Microsoft/go-winio v0.6.2 // indirect
github.com/andybalholm/brotli v1.2.0 // indirect
Expand All @@ -56,25 +56,25 @@ require (
github.com/cucumber/messages/go/v21 v21.0.1 // indirect
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
github.com/distribution/reference v0.6.0 // indirect
github.com/docker/docker v28.5.1+incompatible // indirect
github.com/docker/docker v28.5.2+incompatible // indirect
github.com/docker/go-connections v0.6.0 // indirect
github.com/docker/go-units v0.5.0 // indirect
github.com/ebitengine/purego v0.8.4 // indirect
github.com/ebitengine/purego v0.10.0 // indirect
github.com/felixge/httpsnoop v1.0.4 // indirect
github.com/gabriel-vasile/mimetype v1.4.12 // indirect
github.com/gabriel-vasile/mimetype v1.4.13 // indirect
github.com/go-logr/logr v1.4.3 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/go-ole/go-ole v1.3.0 // indirect
github.com/go-openapi/jsonpointer v0.22.4 // indirect
github.com/go-openapi/jsonreference v0.21.4 // indirect
github.com/go-openapi/spec v0.22.3 // indirect
github.com/go-openapi/swag/conv v0.25.4 // indirect
github.com/go-openapi/swag/jsonname v0.25.4 // indirect
github.com/go-openapi/swag/jsonutils v0.25.4 // indirect
github.com/go-openapi/swag/loading v0.25.4 // indirect
github.com/go-openapi/swag/stringutils v0.25.4 // indirect
github.com/go-openapi/swag/typeutils v0.25.4 // indirect
github.com/go-openapi/swag/yamlutils v0.25.4 // indirect
github.com/go-openapi/jsonpointer v0.22.5 // indirect
github.com/go-openapi/jsonreference v0.21.5 // indirect
github.com/go-openapi/spec v0.22.4 // indirect
github.com/go-openapi/swag/conv v0.25.5 // indirect
github.com/go-openapi/swag/jsonname v0.25.5 // indirect
github.com/go-openapi/swag/jsonutils v0.25.5 // indirect
github.com/go-openapi/swag/loading v0.25.5 // indirect
github.com/go-openapi/swag/stringutils v0.25.5 // indirect
github.com/go-openapi/swag/typeutils v0.25.5 // indirect
github.com/go-openapi/swag/yamlutils v0.25.5 // indirect
github.com/gofrs/uuid v4.3.1+incompatible // indirect
github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 // indirect
Expand All @@ -89,26 +89,26 @@ require (
github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0 // indirect
github.com/leodido/go-urn v1.4.0 // indirect
github.com/lib/pq v1.11.2 // indirect
github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
github.com/lufia/plan9stats v0.0.0-20260216142805-b3301c5f2a88 // indirect
github.com/magiconair/properties v1.8.10 // indirect
github.com/mattn/go-colorable v0.1.14 // indirect
github.com/mattn/go-isatty v0.0.20 // indirect
github.com/mattn/go-runewidth v0.0.20 // indirect
github.com/mattn/go-runewidth v0.0.21 // indirect
github.com/moby/docker-image-spec v1.3.1 // indirect
github.com/moby/go-archive v0.1.0 // indirect
github.com/moby/go-archive v0.2.0 // indirect
github.com/moby/patternmatcher v0.6.0 // indirect
github.com/moby/sys/sequential v0.6.0 // indirect
github.com/moby/sys/user v0.4.0 // indirect
github.com/moby/sys/userns v0.1.0 // indirect
github.com/moby/term v0.5.0 // indirect
github.com/morikuni/aec v1.0.0 // indirect
github.com/moby/term v0.5.2 // indirect
github.com/morikuni/aec v1.1.0 // indirect
github.com/opencontainers/go-digest v1.0.0 // indirect
github.com/opencontainers/image-spec v1.1.1 // indirect
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
github.com/shirou/gopsutil v3.21.11+incompatible // indirect
github.com/shirou/gopsutil/v4 v4.25.6 // indirect
github.com/sirupsen/logrus v1.9.3 // indirect
github.com/shirou/gopsutil/v4 v4.26.2 // indirect
github.com/sirupsen/logrus v1.9.4 // indirect
github.com/spf13/pflag v1.0.7 // indirect
github.com/swaggo/files v1.0.1 // indirect
github.com/tklauser/go-sysconf v0.3.16 // indirect
Expand All @@ -117,30 +117,30 @@ require (
github.com/valyala/fasthttp v1.69.0 // indirect
github.com/yusufpapurcu/wmi v1.2.4 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/contrib v1.20.0 // indirect
go.opentelemetry.io/contrib/bridges/otelzap v0.15.0 // indirect
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.16.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.40.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.40.0 // indirect
go.opentelemetry.io/otel/log v0.16.0 // indirect
go.opentelemetry.io/otel/metric v1.40.0 // indirect
go.opentelemetry.io/otel/sdk/log v0.16.0 // indirect
go.opentelemetry.io/proto/otlp v1.9.0 // indirect
go.opentelemetry.io/contrib v1.42.0 // indirect
go.opentelemetry.io/contrib/bridges/otelzap v0.17.0 // indirect
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.18.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.42.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.42.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.42.0 // indirect
go.opentelemetry.io/otel/log v0.18.0 // indirect
go.opentelemetry.io/otel/metric v1.42.0 // indirect
go.opentelemetry.io/otel/sdk/log v0.18.0 // indirect
go.opentelemetry.io/proto/otlp v1.10.0 // indirect
go.uber.org/multierr v1.11.0 // indirect
go.uber.org/zap v1.27.1 // indirect
go.yaml.in/yaml/v3 v3.0.4 // indirect
golang.org/x/crypto v0.48.0 // indirect
golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93 // indirect
golang.org/x/mod v0.32.0 // indirect
golang.org/x/net v0.50.0 // indirect
golang.org/x/sync v0.19.0 // indirect
golang.org/x/sys v0.41.0 // indirect
golang.org/x/tools v0.41.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260217215200-42d3e9bedb6d // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260217215200-42d3e9bedb6d // indirect
google.golang.org/grpc v1.79.1 // indirect
golang.org/x/exp v0.0.0-20260218203240-3dfff04db8fa // indirect
golang.org/x/mod v0.34.0 // indirect
golang.org/x/net v0.51.0 // indirect
golang.org/x/sync v0.20.0 // indirect
golang.org/x/sys v0.42.0 // indirect
golang.org/x/tools v0.42.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260226221140-a57be14db171 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260226221140-a57be14db171 // indirect
google.golang.org/grpc v1.79.2 // indirect
google.golang.org/protobuf v1.36.11 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
)
Loading
Loading