Skip to main content
Tags are string labels you attach to AgentMark traces for categorization, filtering, and organization. Use tags to slice your trace data by environment, team, feature, experiment, or any other dimension that matters to your workflow.
Developers configure tags in your application code. See Development documentation for setup instructions and SDK examples.

​
How tags work

Tags are stored as an array of strings on each trace. You can attach multiple tags to a single trace, and each tag is a short, descriptive label. When a trace contains multiple spans, tags from all spans are aggregated to the trace level. This means you can set tags on individual spans within a workflow, and they all appear on the parent trace in the dashboard.

​
Viewing tags

Tags appear as a column in the trace list table. Each trace displays its tags as chips, making it easy to scan and identify traces by category at a glance. In the trace detail view, tags are displayed alongside other trace attributes such as metadata, session ID, and user ID.

​
Filtering by tags

You can filter the trace list to show only traces with a specific tag. To filter by tags:
  1. Navigate to the Traces tab in the AgentMark dashboard.
  2. Click the Filters button to open the filter popover.
  3. Select Tags from the field dropdown.
  4. Choose an operator and enter the tag value you want to match.
  5. Click Apply.
For full details on filter operators and combining multiple filters, see the Filtering and search documentation.

​
Setting tags

Tags are set via the AgentMark SDK at trace creation time. You pass tags as an array of strings when creating a trace or span. 
import { trace } from "@agentmark-ai/sdk";

const { result, traceId } = await trace(
  {
    name: "user-request",
    tags: ["production", "chat-v2", "team-alpha"],
  },
  async (ctx) => {
    // Your logic here
  }
);
For full implementation details and additional examples, see the Development documentation for tags.

​
Best practices

​
Use consistent naming conventions

Establish a standard format for tag names across your team. Kebab-case works well for readability and consistency.
  • Do: production, team-alpha, experiment-v2, chat-feature
  • Avoid: Production, Team Alpha, experimentV2, CHAT_FEATURE

​
Keep tags short and descriptive

Tags should be concise labels that are easy to scan in the trace list. Aim for one to three words per tag.

​
Use tags for dimensions you filter by frequently

Tags are optimized for filtering and grouping. If you find yourself repeatedly searching for traces by a particular dimension, that dimension is a good candidate for a tag.

​
Recommended tag patterns

  • Environment — production, staging, development. Separate environments within a single AgentMark app.
  • Team — team-alpha, team-platform, team-growth. Attribute traces to the team that owns the feature.
  • Feature — chat-v2, search-rerank, onboarding-flow. Track which feature generated the trace.
  • Experiment — exp-baseline, exp-new-prompt, exp-rag-v3. Label traces for A/B testing and prompt experiments.
  • Release — v2.1.0, canary, rc-4.0. Track which release version generated the trace.

​
Do not use tags for unique values

Tags are designed for categorical labels with a small set of known values. If you need to attach unique identifiers like user IDs, request IDs, or configuration values, use metadata instead.

​
Limits

  • Tag length: Each tag can be up to 200 characters.
  • Tags per trace: No hard limit, but keep the set small for readability and filter performance.
  • Tag format: Tags are case-sensitive strings. production and Production are treated as different tags.

​
Tags vs metadata

AgentMark provides both tags and metadata for enriching traces. Choose the right tool for the job: Tags are categorical string labels for filtering and grouping.
  • Stored as an array of strings on each trace.
  • Best for dimensions with a small, known set of values (environments, teams, features).
  • Optimized for quick filtering in the dashboard.
Metadata is arbitrary key-value pairs for context and debugging.
  • Stored as a string-to-string map on each trace.
  • Best for unique identifiers (user IDs, request IDs), configuration values, and request-specific data.
  • Supports richer filter operators (contains, starts with, exists).
A good rule of thumb: if you would use it as a label or category, make it a tag. If you would use it as a lookup key or identifier, make it metadata.

​
Next steps

Filtering and search

Combine tags with other filters to find specific traces

Metadata

Attach key-value pairs for context and debugging

Traces and logs

Understand trace details and span attributes

Development setup

Set up tags in your application code

​
Have Questions?

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