Spans, attributes, and outcomes

A span describes one operation, with attributes for its scope, outcome, and measured counts. Some fields explicitly identify the enclosing request or job; count units depend on the span kind.

Span structure

REST and hosted HTTP MCP use an HTTP entry span, while direct network gRPC calls use a gRPC server span. The internal REST/MCP-to-gRPC bridge preserves parentage without extra transport spans.

A retrieval trace can show a structure like this:

Request
  Retrieval
    Query preparation and embedding
      Provider call
        Attempts and retry waits
    Search and result preparation
    Postprocessing
      Rerank or generation call

The request determines which operations appear. Parallel stages can overlap, so their duration sum can exceed the request duration. Provider observations also cover ingestion and provider checks outside retrieval. Use the generated span inventory for the current span names.

The inference proxy supplies transport traces only, without semantic generation spans or token counts. SQL spans require separate instrumentation.

Request and resource filters

Retrieval space fields describe the authorized search scope. A truncated list can omit a space that the request searches. If goodmem.retrieval.space_ids_truncated is true, a negative match cannot exclude an omitted space. The generated inventory lists the vendor aliases for these fields. Principal IDs remain resource metadata rather than backend application-user or session IDs.

Outcomes and errors

goodmem.outcome has four values:

Common categories include authentication, permission, timeout, and provider_failure. Other values can appear in later versions.

For cross-provider failure filters, use goodmem.failure.category; transport spans retain their native error.type conventions.

Result counts

A result count describes the output of the span that carries it, rather than one universal unit for the request. For example, retrieval counts describe emitted results, while vector-search counts describe candidate hits. Do not sum result counts across spans.

A stage reports a count only when the operation supplies one. See the generated mappings for the fields that use the destination alias result_count.

Provider usage and retries

gen_ai.usage.input_tokens and gen_ai.usage.output_tokens contain the nonnegative token counts that the provider reports. An absent counter means unknown usage; an explicit zero means reported zero. See the generated inventory for usage fields, retry counters, and vendor aliases.

Background jobs

Each execution attempt starts a new trace, separate from the original enqueue request. Use goodmem.job.id to correlate attempts, or goodmem.job.attempt.id and goodmem.job.attempt.number to select one attempt. Attempt duration covers execution only, without queue delay or time between durable retries.

Attribute limits

GoodMem bounds the number of attributes, text length, and array size per span. The counters goodmem.telemetry.dropped_field_count and goodmem.attributes.dropped_count report omissions from these controls.

Generated span inventory

This table lists named spans from GoodMem source. HTTP route names and spans from dependency instrumentation vary with the request.

Generated attribute inventory

This inventory covers goodmem.* and gen_ai.* declarations in GoodMem source, without attributes from dependency instrumentation. In goodmem.result.status_count.<code>, <code> is a lowercase gRPC status name. Each span contains only the fields that its operation supplies.

The type column describes canonical OTLP values: int64 is an integer, and float64 is a floating-point number. Langfuse scalar metadata aliases use strings. LangSmith metadata preserves canonical types.

The metadata columns list destination aliases; a dash marks fields without an alias, whose canonical attributes remain available. Standard GenAI fields also use native backend mappings.

Langfuse prefixes aliases with langfuse.observation.metadata., while LangSmith stores them in its JSON metadata attribute.