Overview

Rails Pulse includes a flexible tagging system that allows you to categorize and organize your performance data. Tag routes, requests, queries, jobs, and job runs with custom labels to better organize and filter your monitoring data.

Tags help you:

• Organize data by environment, priority, team, or any custom category
• Filter quickly to find specific issues or patterns
• Track progress by marking items as “investigating” or “resolved”
• Collaborate by categorizing work across teams

Configuring Tags

Define available tags in your Rails Pulse initializer. Tags are shared across all record types (routes, requests, queries, jobs, and job runs).

RailsPulse.configure do |config|
  config.tags = [
    "production",
    "staging",
    "critical",
    "needs-optimization",
    "high-traffic",
    "background-job"
  ]
end

Note: After adding or modifying tags, restart your Rails server for changes to take effect.

Using Tags

Tagging from the UI

You can tag any route, request, query, job, or job run directly from the Rails Pulse dashboard:

1. Navigate to any route, request, query, job, or job run detail page
2. Click the ”+ tag” button next to the record
3. Select from your configured tags in the dropdown
4. Remove tags by clicking the × button on any tag badge

Programmatic Tagging

You can also manage tags programmatically using the Rails console or in your application code:

# Tag a route
route = RailsPulse::Route.find_by(path: "/api/users")
route.add_tag("critical")
route.add_tag("high-traffic")

# Tag a query
query = RailsPulse::Query.find_by(normalized_sql: "SELECT * FROM users WHERE id = ?")
query.add_tag("needs-optimization")

# Tag a job
job = RailsPulse::Job.find_by(name: "UserNotificationJob")
job.add_tag("high-priority")
job.add_tag("user-facing")

# Tag a specific job run
job_run = RailsPulse::JobRun.find_by(run_id: "abc123")
job_run.add_tag("investigated")

# Remove a tag
route.remove_tag("critical")

# Check if has tag
route.has_tag?("production") # => true

# Get all tags for a record
route.tag_list # => ["high-traffic"]

Filtering by Tags

Use the global filters modal to filter performance data by tags throughout the dashboard:

1. Click the filter icon in the top navigation
2. Select one or more tags from the tag selector
3. Apply filters to see only records with those tags
4. Clear filters to return to the full data view

Tags appear as color-coded badges in all data tables for quick visual identification. You can combine multiple filters to narrow down your search.

Common Tagging Strategies

Here are some proven strategies for organizing your performance data with tags:

By Environment

config.tags = ["production", "staging", "development"]

Useful for tracking issues specific to certain environments, especially when using the same Rails Pulse instance across multiple environments.

By Priority

config.tags = ["critical", "high", "medium", "low"]

Helps prioritize performance issues and focus on the most impactful optimizations first.

By Status

config.tags = ["needs-optimization", "investigating", "resolved", "monitoring"]

Track the lifecycle of performance issues from discovery through resolution.

By Type

config.tags = ["api", "background-job", "user-facing", "admin", "internal"]

Categorize endpoints and jobs by their function or audience.

By Team

config.tags = ["team-frontend", "team-backend", "team-data", "team-mobile"]

In larger organizations, assign ownership of routes and jobs to specific teams.

Combined Strategy

For maximum flexibility, combine multiple strategies:

config.tags = [
  # Environment
  "production", "staging",

  # Priority
  "critical", "high", "medium", "low",

  # Status
  "needs-optimization", "investigating", "resolved",

  # Type
  "api", "background-job", "user-facing", "admin",

  # Team
  "team-frontend", "team-backend", "team-data"
]

Best Practices

Keep Tags Concise

Use short, descriptive names (1-3 words) that are easy to scan in the UI. Avoid lengthy descriptions.

Establish Conventions

Document your tagging strategy and naming conventions for your team. Consistency makes tags more useful.

Don’t Over-Tag

Start with 10-15 essential tags. Too many tags can make filtering overwhelming. Add more as needed.

Use Tags for Actions

Tags like “needs-optimization” or “investigating” indicate actionable items, making it easy to track TODOs.

Clean Up Obsolete Tags

Periodically review and remove tags that are no longer relevant. Remove unused tags from the configuration.

Tag Early

Tag routes and jobs as soon as you identify patterns or issues. This builds a valuable knowledge base over time.

Next Steps

Advanced Configuration

Explore performance thresholds, filtering, and data cleanup options.

Advanced Settings →

Performance Impact

Learn about Rails Pulse’s performance overhead and optimization strategies.

Performance Guide →