This repository is the language-neutral contract for telemetry emitted by Bitsmithy services and shared libraries. Stable OpenTelemetry semantic conventions take precedence. This contract defines only the common custom instruments, attributes, units, outcomes, privacy limits, and compatibility rules that Bitsmithy needs in addition.
contract.json is the machine-readable contract.
contract.sha256 pins its exact content.
The current contract version is 1.1.0.
Validate the published contract with:
make testLanguage libraries vendor the contract and checksum that they implement. They do not download this repository at application runtime.
- Durations use seconds.
- HTTP metrics use route patterns, not concrete request paths.
- Product Actions record one deliberate user gesture, not one count per affected record.
- Product Action actors are
cook,guest, oranonymous. - Product Action outcomes are
success,rejected, orerror. - Idempotent state-changing actions can set
app.user.action.changedtofalsewhile retainingsuccess. - Actions can set
app.user.action.variantonly to a value from the contract's finite list. - Stable resource attributes identify service namespace, service name, service version, and deployment environment.
Metrics use controlled, application-bounded values. Do not attach credentials, database binds, emails, free text, record or user identifiers, session tokens, SQL statements, or concrete URLs. Do not parse SQL to create table-name labels. Trace attributes follow the same rules unless a later contract version explicitly permits a bounded value.
Patch releases clarify the contract without changing emitted telemetry. Minor releases add optional definitions or values. Major releases rename or remove definitions, change units, or change meaning.
MIT