mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-20 14:13:23 +00:00
A spend row could say what a call cost and not who caused it. The credential that placed the call was written into the user column, so an application — a program, which cannot owe anyone money — read as the customer. Over half a month's inference arrived attributed to a service account, and the query for unattributed spend found nothing, because by that column every row had an owner. bind is now the one place a record learns its principal, replacing a name written at each of 35 emit sites. Only a person is named: a person's credential names itself and no header can move it, a machine is recorded as the agent and names whoever the identity boundary authenticated before it, and a machine naming nobody leaves the column empty and says so. Attribution stays separate from settlement — naming a person never moves money. Alongside it the row gained the host that answered, the credential ref, and the conversation. Provider is our label for a route; origin is the address the bytes went to. Two columns can disagree, and that disagreement is the measurement — a customer sees the label, and we can still see who served it. The schema was stated in three places said to be kept in lockstep by comment, and four columns were declared, documented, populated on the record, and written by nothing. Empty is indistinguishable from unused, so they read as no-data. The write order is now one list the statement derives from, and tests fail on a column that is declared and never written.
86 lines
3.7 KiB
Go
86 lines
3.7 KiB
Go
// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
package object
|
|
|
|
import "context"
|
|
|
|
// Request-scoped observability attribution carried on the Go request context.
|
|
//
|
|
// The TenantContextFilter (routers) stashes the caller's project sub-scope and a
|
|
// non-reversible ref of the caller credential here; recordTrace (controllers)
|
|
// reads it once to stamp BOTH the cloud_usage ledger row and the gen_ai span. This
|
|
// lives in `object` (the shared lower layer both routers and controllers import)
|
|
// so neither package depends on the other — one context key, one home.
|
|
|
|
type genAIAttrKey struct{}
|
|
|
|
// GenAIAttribution is the per-request attribution the gen_ai span + cloud_usage
|
|
// ledger stamp. Every field is optional; an empty field emits/stores nothing.
|
|
type GenAIAttribution struct {
|
|
// Org is the caller's VERIFIED tenant org (GetOrg — the principal's real org, not
|
|
// the raw X-Org-Id header). recordTrace stamps it onto the gen_ai span's
|
|
// gen_ai.hanzo.org_id ONLY as a fallback when a producer left the record's
|
|
// org/owner empty, so real tenant traffic always carries its org even on a code
|
|
// path that forgot to set it. The o11y llmobs views apply a mandatory org filter
|
|
// that silently drops empty-org spans — this closes that hole.
|
|
Org string
|
|
// Project is the caller's org SUB-SCOPE (X-Project-Id); "" is the default project.
|
|
Project string
|
|
// Session is the client-supplied session/conversation id (X-Session-Id). It turns
|
|
// the o11y sessions view on for this org (emitted as session.id + gen_ai.conversation.id).
|
|
Session string
|
|
// Environment is the caller's logical environment label (X-Environment, e.g.
|
|
// "staging"/"production"). Stamped onto the span's deployment.environment so
|
|
// Observe stops defaulting to "default". "" emits nothing.
|
|
Environment string
|
|
// APIKeyHash is a SHA-256 hex ref of the caller credential — NEVER the plaintext key.
|
|
APIKeyHash string
|
|
// User is the person the caller is acting for (X-User-Id), as "<org>/<name>".
|
|
// A service credential authenticates a human and then buys inference on that
|
|
// human's behalf, so the credential names itself and this names the person. It
|
|
// is honored ONLY for a machine credential (usageRecord.bind): a person's own
|
|
// credential already names a person, and letting it name a different one would
|
|
// let anyone move their spend onto a colleague.
|
|
User string
|
|
}
|
|
|
|
// empty reports whether a carries nothing worth threading.
|
|
func (a GenAIAttribution) empty() bool {
|
|
return a.Org == "" && a.Project == "" && a.Session == "" && a.Environment == "" &&
|
|
a.APIKeyHash == "" && a.User == ""
|
|
}
|
|
|
|
// WithGenAIAttribution returns ctx carrying a. When a is empty it returns ctx
|
|
// unchanged (no allocation, no value to read back).
|
|
func WithGenAIAttribution(ctx context.Context, a GenAIAttribution) context.Context {
|
|
if ctx == nil {
|
|
return ctx
|
|
}
|
|
if a.empty() {
|
|
return ctx
|
|
}
|
|
return context.WithValue(ctx, genAIAttrKey{}, a)
|
|
}
|
|
|
|
// GenAIAttributionFromContext returns the attribution stashed on ctx, or the zero
|
|
// value when none is present.
|
|
func GenAIAttributionFromContext(ctx context.Context) GenAIAttribution {
|
|
if ctx == nil {
|
|
return GenAIAttribution{}
|
|
}
|
|
a, _ := ctx.Value(genAIAttrKey{}).(GenAIAttribution)
|
|
return a
|
|
}
|