JuliusBrussee/caveman · error

telemetry attribute key exceeds

Error message

telemetry attribute key exceeds %d bytes

What it means

SanitizeAttributes rejects any attribute key longer than MaxAttributeKeyBytes. Boundaries are checked after sorting allowed keys; the first oversized key aborts the whole sanitize operation with an error (fail-closed, no truncation).

Solutions

1. Shorten the attribute key to a bounded, well-known name.
2. Move the long value into the attribute VALUE (bounded by MaxAttributeValueBytes) and use a short key like error.detail.
3. Sanitize keys at instrumentation time (trim/hash long identifiers).
4. Prefer ASCII/short keys to avoid multi-byte surprises.

Example fix

// before
attrs["/very/long/path/to/failed/module/segment/that/exceeds/limit"] = "true"

// after
attrs["failed.module"] = "/very/long/path/to/failed/module" // long data as value, short key

for k := range attrs {
    if len(k) > maxAttrKeyBytes /* mirror MaxAttributeKeyBytes */ {
        return fmt.Errorf("precheck: key %q too long", k)
    }
}

sanitized, err := telemetry.SanitizeAttributes(raw)
if err != nil && strings.Contains(err.Error(), "key exceeds") {
    raw = shortenKeys(raw) // map long keys to fixed short names
    sanitized, err = telemetry.SanitizeAttributes(raw)
}

When it happens

Trigger: Parse called on a span whose attribute map contains a key whose byte length exceeds MaxAttributeKeyBytes (note: bytes, so multi-byte UTF-8 keys hit the limit sooner).

Common situations: Using full error strings or file paths as attribute keys; programmatically generated keys embedding long identifiers; non-ASCII keys consuming several bytes per character.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• telemetry attribute exceeds bytes
• telemetry attributes exceed
• cave_budget_release_exceeds_max
• invalid decompression limit
• telemetry attributes exceed

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/f245d085f1d5dcb1. Report an issue: GitHub.

Appendix: source

Thrown at shared/platform/telemetry/span.go:265

// SanitizeAttributes returns a deterministic copy. Sensitive keys are removed;
// malformed or oversized metadata fails closed so callers can reject the record.
func SanitizeAttributes(attrs map[string]string) (map[string]string, error) {
	keys := make([]string, 0, len(attrs))
	for key := range attrs {
		if AttributeAllowed(key) {
			keys = append(keys, key)
		}
	}
	if len(keys) > MaxAttributes {
		return nil, fmt.Errorf("telemetry attributes exceed %d keys", MaxAttributes)
	}
	sort.Strings(keys)
	out := make(map[string]string, len(keys))
	total := 0
	for _, key := range keys {
		value := attrs[key]
		if len(key) > MaxAttributeKeyBytes {
			return nil, fmt.Errorf("telemetry attribute key exceeds %d bytes", MaxAttributeKeyBytes)
		}
		if len(value) > MaxAttributeValueBytes {
			return nil, fmt.Errorf("telemetry attribute %q exceeds %d bytes", key, MaxAttributeValueBytes)
		}
		total += len(key) + len(value)
		if total > MaxAttributesBytes {
			return nil, fmt.Errorf("telemetry attributes exceed %d bytes", MaxAttributesBytes)
		}
		out[key] = value
	}
	return out, nil
}

View on GitHub (pinned to 3ee70a1026)