Skip to main content
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

Pass a tags array when creating a trace. All spans within the trace inherit these tags: 
import { trace } from "@agentmark-ai/sdk";

const { result, traceId } = await trace(
  {
    name: "user-request",
    tags: ["production", "chat-v2", "team-alpha"],
    metadata: { userId: "user-123" },
  },
  async (ctx) => {
    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

Tags set on the parent trace are aggregated to the trace level. You can also set tags on individual child spans: 
const { result } = await trace(
  { name: "multi-step-workflow", tags: ["production", "search-feature"] },
  async (ctx) => {
    await ctx.span({ name: "retrieval-step" }, async (spanCtx) => {
      spanCtx.setAttribute("agentmark.tags", JSON.stringify(["rag-v3"]));
    });
  }
);
// Dashboard shows all three tags: 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
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.

​
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 & Search

Combine tags with other filters

​
Have Questions?

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