Instrumentation Naming & Event Contract Template

{ "Title": "Event Contract Template", "IntroductionHtml": "

Purpose

This template captures a clear, discoverable contract for a tracked event: its canonical name, payload schema, ownership, versioning, privacy considerations, test requirements, and rollout plan. Use it to avoid accidental telemetry artifacts, make events discoverable, and enable reliable downstream analysis.

Naming conventions (quick rules)

• Use lowercase, dot-separated namespaces: <domain>.<entity>.<action> (e.g., orders.checkout.completed).
• Prefer business semantics over implementation details.
• Avoid verbs that imply system internals (use completed/succeeded/failed rather than ack).
• Include version in the contract, not the name; use a separate version field for evolution.

How to use

Complete the fields below, attach or link a machine-readable schema (JSON Schema, Avro, Protobuf), and add tests. Save the contract and notify known consumers before rolling out changes.

", "SubmitLabel": "Save Event Contract", "SuccessMessage": "Event contract saved. You can update it later, export the JSON, or notify consumers.", "DataType": "EventContract", "SchemaVersion": "1.0", "Fields": [ { "Key": "event_name", "FieldType": "text", "Label": "Canonical event name", "HelpText": "Lowercase dot-separated namespace.entity.action (required). Example: orders.checkout.completed", "Required": true }, { "Key": "event_namespace", "FieldType": "text", "Label": "Namespace / domain", "HelpText": "High-level domain or team responsible for the event (e.g., orders, payments).", "Required": true }, { "Key": "event_version", "FieldType": "text", "Label": "Contract version", "HelpText": "Semantic style recommended (e.g., 1.0, 2.0) or a simple integer. Increment when payload or semantics change in incompatible ways.", "Required": true }, { "Key": "short_description", "FieldType": "textarea", "Label": "Short description", "HelpText": "One-sentence business meaning of the event. Explain what the event represents and why it exists.", "Required": true }, { "Key": "producer_service", "FieldType": "text", "Label": "Producer service / component", "HelpText": "Service, component, or team that emits the event.", "Required": true }, { "Key": "owner_contact", "FieldType": "text", "Label": "Event owner (contact)", "HelpText": "Person or team responsible for contract changes and consumer inquiries (name, team, email or ticket queue).", "Required": true }, { "Key": "known_consumers", "FieldType": "textarea", "Label": "Known consumers", "HelpText": "List systems, teams, dashboards, models, or reports that rely on this event (helps impact analysis).", "Required": false }, { "Key": "business_context", "FieldType": "textarea", "Label": "Business context / usage examples", "HelpText": "Concrete examples of how the event is used in business logic, KPIs, or analytics (helps avoid accidental renames).", "Required": false }, { "Key": "payload_schema_location", "FieldType": "text", "Label": "Schema location (URL or repo path)", "HelpText": "Link to machine-readable schema (JSON Schema / Avro / Protobuf). Prefer a versioned artifact located in a registry or repo.", "Required": true }, { "Key": "required_payload_fields", "FieldType": "textarea", "Label": "Required payload fields", "HelpText": "List required fields, types, and short meanings. Example: order_id (string) — canonical order identifier. Use one per line.", "Required": true }, { "Key": "optional_payload_fields", "FieldType": "textarea", "Label": "Optional payload fields", "HelpText": "List optional fields, types, and meanings. Specify default values if any.", "Required": false }, { "Key": "sample_payload", "FieldType": "textarea", "Label": "Example payload", "HelpText": "Provide a representative JSON example (pretty-printed). Helps consumers understand typical and edge cases.", "Required": false }, { "Key": "privacy_sensitive", "FieldType": "yesno", "Label": "Contains privacy-sensitive or regulated data?", "HelpText": "If yes, describe PII, PHI or other regulated fields below and reference compliance controls.", "Required": true }, { "Key": "pii_fields", "FieldType": "textarea", "Label": "PII / regulated fields", "HelpText": "List fields considered PII/PHI or subject to special handling, masking, or encryption. Leave blank if not applicable.", "Required": false }, { "Key": "retention_policy", "FieldType": "text", "Label": "Retention / storage policy", "HelpText": "How long raw events and derived artifacts should be retained, and where. Reference storage class or bucket where applicable.", "Required": false }, { "Key": "compliance_notes", "FieldType": "textarea", "Label": "Compliance or legal notes", "HelpText": "Any regulatory or contractual considerations analysts and engineering must know before using the event.", "Required": false }, { "Key": "versioning_strategy", "FieldType": "select", "Label": "Versioning strategy", "HelpText": "How incompatible vs. compatible changes are handled.", "Options": [ {"Value": "semantic", "Label": "Semantic (major.minor)", "Selected": true}, {"Value": "incremental", "Label": "Incremental integer"}, {"Value": "calendar", "Label": "Calendar/date-based"} ], "Required": true }, { "Key": "change_impact_notes", "FieldType": "textarea", "Label": "Change impact & migration guidance", "HelpText": "Describe how to migrate consumers, compatibility guarantees, and whether older versions will be retained.", "Required": false }, { "Key": "automated_tests", "FieldType": "checkbox", "Label": "Automated tests to include", "HelpText": "Pick tests that must run for this contract to be considered healthy.", "Options": [ {"Value": "schema_validation", "Label": "Schema validation"}, {"Value": "contract_tests", "Label": "Consumer contract tests (mocks)"}, {"Value": "end_to_end", "Label": "End-to-end smoke tests"}, {"Value": "monitoring_alerts", "Label": "Monitoring/alert checks for volume/format"} ] }, { "Key": "test_checklist", "FieldType": "textarea", "Label": "Test & validation checklist", "HelpText": "Short checklist to validate event before rollout (e.g., schema passes, sample payloads emitted, consumers smoke-tested).", "Required": false }, { "Key": "validation_run_command", "FieldType": "text", "Label": "Validation command / CI job name", "HelpText": "CI job or script name that runs contract validation (e.g., ci/event-contract-validate).", "Required": false }, { "Key": "consumers_notification_strategy", "FieldType": "textarea", "Label": "Consumer notification plan", "HelpText": "How known and potential consumers will be notified of changes (mailing list, changelog, deprecation window).", "Required": false }, { "Key": "rollout_plan", "FieldType": "textarea", "Label": "Rollout / deployment plan", "HelpText": "Phases, feature flags, canary windows, and rollback criteria.", "Required": false }, { "Key": "deprecation_policy", "FieldType": "textarea", "Label": "Deprecation policy", "HelpText": "How and when old versions will be deprecated and removed. Include minimum notice period.", "Required": false }, { "Key": "related_metrics", "FieldType": "textarea", "Label": "Related KPIs or metrics", "HelpText": "Metrics or dashboards that rely on this event (helps prioritize stability).", "Required": false }, { "Key": "approval_status", "FieldType": "select", "Label": "Approval status", "HelpText": "Contract lifecycle state.", "Options": [ {"Value": "draft", "Label": "Draft", "Selected": true}, {"Value": "proposed", "Label": "Proposed"}, {"Value": "approved", "Label": "Approved"}, {"Value": "deprecated", "Label": "Deprecated"} ], "Required": true }, { "Key": "last_updated_by", "FieldType": "text", "Label": "Last updated by", "HelpText": "Name or id of the person who last edited this contract.", "Required": false }, { "Key": "notes", "FieldType": "textarea", "Label": "Additional notes", "HelpText": "Any other information helpful to consumers or maintainers.", "Required": false } ] }