/migrating-to-lib-observability

name: ring:migrating-to-lib-observability
description: "Migrating a Lerian Go app off lib-commons observability imports (deprecated shims or removed APIs) to lib-observability via a fixed mapping table, then bumps go.mod and validates the build; ring:backend-go applies the edits. Covers log/zap/runtime/assert, opentelemetry/tracing, HTTP middleware, context helpers, and direct systemplane import moves. Use when lib-commons observability imports remain or the build breaks on removed APIs."

Migrate lib-commons Observability APIs to lib-observability

When to use

• Application imports one or more lib-commons observability packages/symbols listed in the mapping table below
• Team decision to eliminate deprecation warnings from lib-commons shims
• lib-commons deprecation notices appear in IDE or go vet output
• Application no longer builds because lib-commons has removed observability APIs and source imports still reference them

Skip when

• Application already imports lib-observability for all observability concerns
• Application has no imports of the lib-commons observability packages/symbols listed below
• Application is lib-commons itself

**Do NOT skip when:**

• "The app only imports log/ from lib-commons" → still migrate; log is an observability target
• "The app uses streaming/kafka" → streaming is out of scope; only observability packages and HTTP/gRPC observability middleware migrate
• "The app uses commons/opentelemetry for tracing bootstrap" → migrate when `lib-observability/tracing` exposes the target API (helper-only files first, bootstrap when type boundaries allow)
• "`go list` or `go build` fails because lib-commons removed the observability APIs" → still migrate; this skill performs static source rewrites against the known mapping table even when the source packages no longer exist

Sequence

**Runs before:** (none) **Runs after:** (none)

Related

**Complementary:** ring:using-ring, ring:running-dev-cycle, ring:reviewing-code, ring:fixing-lint, ring:using-lib-commons

---

Overview

This skill replaces imports/usages of lib-commons observability APIs with their canonical lib-observability equivalents.

**Stable target baseline for this migration:**

• `github.com/LerianStudio/lib-commons/v5` >= `v5.7.0`
• `github.com/LerianStudio/lib-observability` >= `v1.1.0`
• `github.com/LerianStudio/lib-auth/v2` >= `v2.8.0` when present
• `github.com/LerianStudio/lib-license-go/v2` >= `v2.3.5` when present
• `github.com/LerianStudio/lib-streaming` >= `v1.3.1` when present
• `github.com/LerianStudio/lib-systemplane` >= `v1.0.0` when systemplane is used

`lib-commons/v5.7.0` is the current stable lib-commons target for this migration (the deprecated observability shims were first removed in `v5.2.0`). `lib-observability/v1.1.0` is the current stable lib-observability target release (`v1.0.0` was the first stable release). `lib-auth/v2.8.0` and `lib-license-go/v2.3.5` are the first stable companion releases known to be compatible with the removed lib-commons observability APIs. `lib-streaming/v1.3.1` is the first stable streaming release in this validation set that no longer imports removed lib-commons observability packages. `lib-systemplane/v1.0.0` is the stable package destination for direct `commons/systemplane` imports removed from lib-commons. Do not use beta tags for new migrations unless the target application is intentionally pinned to a beta train.

**Known lib-commons observability removal refs:**

• Removal commit: `fe1db9e60ac9e959de4288208b6cf65f7bbfe439`

(`refactor: remove deprecated commons observability shims`)

• First stable removal release: `v5.2.0`
• Pre-removal reference: `fe1db9e60ac9e959de4288208b6cf65f7bbfe439^`

(currently `a33b160ac165cff8b4ddf5c69d8dbb80a10868f6`)

Use the pre-removal reference as the default source-evidence ref when the effective lib-commons dependency has already removed the deprecated shims and the user did not provide `lib_commons_pre_removal_ref`. That ref still contains the `Deprecated:` notices while using lib-observability types internally.

**Targeting strategy:** migrate known observability APIs when the target API exists in the effective lib-observability version. Source-side `Deprecated:` notices are preferred evidence. Read them from the effective lib-commons version when available; if a removal commit/ref is known, read them from the immediate pre-removal lib-commons ref. If neither source is available because lib-commons has already removed the package/symbol, the application may not compile, and the skill must still migrate by static source analysis.

If a target API is missing from lib-observability, do not migrate that API. Report the missing target and leave the lib-commons usage unchanged unless it is already broken by removal; in that case report it as a manual migration blocker.

In removed-api mode, package-level imports such as `commons/log` can still cross non-observability lib-commons boundaries (for example `mongo.Config.Logger`, `postgres.Config.Logger`, `WithCORSLogger`, `circuitbreaker.NewManager`, auth middleware, outbox/tenant-manager clients, streaming builders, or any remaining lib-commons API typed as `commons/log.Logger`). Do not invent adapters in the skill. Migrate safe source files, run build validation, and if a file fails only because a migrated value crosses a remaining lib-commons typed boundary, revert that file/family to lib-commons and report it as a manual blocker.

Also check transitive dependencies after bumping lib-commons to a removal release. If `go build` fails from `$GOMODCACHE` with errors such as `no required module provides package github.com/LerianStudio/lib-commons/v5/commons/log`, `commons/zap`, or `commons/opentelemetry`, the target repo was migrated as far as local source allows, but one of its dependencies still depends on removed lib-commons observability packages. First try the known stable companion bumps when the modules are present:

GONOSUMDB="git