Tagging and Filtering Your Data in Hud

Use custom tags to slice your metrics and focus on the service sessions that matter to you.

1. Add Tags in Your SDK Configuration

Tags are defined in your SDK initialization block as key-value pairs. All metrics sent from that service session will carry those tags.

Tags Format

import * as hud from 'hud-sdk/setup';

hud.initSession(
  "<API_KEY>",
  "<Service>",
  {
    tags: {
      "region": "us-east",
      "job": "worker-A",
      "language": "node"
    },
  }
);

import hud_sdk

hud_sdk.init_session(
  "<API_KEY>",
  "<Service>",
  tags={
    "region": "us-east",
    "job": "worker-A",
    "language": "python"
  }
)

java -javaagent:./hud-sdk.jar \
  -Dio.hud.tags.region=us-east \
  -Dio.hud.tags.job=worker-A \
  -Dio.hud.tags.language=java \
  -jar [app.jar]

Note:

You can use any string key and string value.
Tags are sent once per session and apply to all metrics from that session.
In Java, tags are passed as -Dio.hud.tags.<key>=<value> system properties rather than in an init block, since the agent is attached at startup. A . in a tag key is replaced with _.

2. Filter Data in the Hud Web App and MCP Tools

Web App

Once you've run your service with tags, you can use the Tag filter at the top of any metrics page (Overview, Endpoints, Functions, Queues).

Select one or more tag keys (e.g., "region") -> Then choose values (e.g., "us-east", "eu-west")

Note:

Filters are reflected in the URL and persist as you navigate
You’ll only see metrics from sessions that match all selected tags
You can only filter by tags that were seen in one of your service sessions within the last 6 months. If no recent tags exist, the filter selector will not appear.

MCP Tools

If you're using Hud in your IDE, your agent can request filtered results using the same tag values.

Just ask your agent to request metrics for a specific tag or tag combination.
- For example:
  
  Show me the top endpoints for region=us-east and job=worker-A
Your agent will automatically request the matching data from Hud MCP with the relevant tag filters. Note: If no tag filters are passed, all data is returned.

FAQ

Q: Can I add tags dynamically at runtime?

A: Not yet. Tags must be set when initializing the SDK.

Q: Are filters case-sensitive?

A: No. Tag keys and values are matched in a case-insensitive way.

Q: Where can I see which tags are active in my account?

A: All detected tags will show up in the tag filter UI in the web app.

Need help? Contact us →