Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt

Use this file to discover all available pages before exploring further.

Tags are string labels you attach to traces for categorization, filtering, and organization. Use tags to slice trace data by environment, team, feature, experiment, or any other dimension.

​
Setting tags

Tags are attached to a span by setting the agentmark.tags span attribute. The gateway accepts a JSON array string, a comma-separated string, or a native array. Set the attribute inside a span() callback using ctx.setAttribute(). The tag list is aggregated to the parent trace in the Dashboard. 
import { span } from "@agentmark-ai/sdk";

const { result, traceId } = await span(
  {
    name: "user-request",
    metadata: { userId: "user-123" },
  },
  async (ctx) => {
    ctx.setAttribute(
      "agentmark.tags",
      JSON.stringify(["production", "chat-v2", "team-alpha"])
    );

    const prompt = await client.loadTextPrompt("handler.prompt.mdx");
    const input = await prompt.format({
      props: { query: "Hello" },
      telemetry: { isEnabled: true },
    });
    return await generateText(input);
  }
);

​
Tags on child spans

You can set tags on any span — the gateway aggregates tags across a trace’s spans into the trace-level tag list shown in the Dashboard. 
const { result } = await span(
  { name: "multi-step-workflow" },
  async (ctx) => {
    ctx.setAttribute(
      "agentmark.tags",
      JSON.stringify(["production", "search-feature"])
    );

    await ctx.span({ name: "retrieval-step" }, async (spanCtx) => {
      spanCtx.setAttribute("agentmark.tags", JSON.stringify(["rag-v3"]));
    });
  }
);
// Dashboard shows three tags on the trace: production, search-feature, rag-v3

​
Filtering by tags

Tags appear as a column in the trace list. Filter by navigating to Traces, clicking Filters, selecting Tags, and choosing an operator and value.

​
Tags vs metadata

TagsMetadata
FormatArray of stringsKey-value pairs (string → string)
Best forCategorical labels (environment, team, feature)Unique identifiers (user IDs, request IDs)
Set sizeSmall, known set of valuesUnlimited unique values
If you would use it as a label or category, make it a tag. If you would use it as a lookup key, make it metadata.

​
Limits

  • Up to 20 tags per span (extra tags are dropped by the gateway).
  • Each tag is trimmed and must be 1–100 characters. Longer tags are dropped.
  • Empty strings are ignored.

​
Best practices

  • Use kebab-case — production, team-alpha, chat-v2 (not Production, team_alpha)
  • Define tags as constants to avoid typos
  • Keep the tag set small — Tags with hundreds of unique values belong in metadata
  • Recommended patterns: environment (production, staging), team (team-alpha), feature (chat-v2), experiment (exp-new-prompt), release (v2.1.0)

Metadata

Key-value pairs for context and debugging

Filtering and search

Combine tags with other filters

​
Have Questions?

We’re here to help! Choose the best way to reach us: