Skip to main content
Use Cases
  • Attributing token costs and latency to specific features or services.
  • Monitoring which internal tools or products drive the most LLM usage.
  • Filtering observability dashboards by application for debugging or billing.
  • Enforcing separate budgets per product line or team.

​
Quick Start

Name your requests to track usage by application or service. 
curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "input": "Write a professional email",
    "name": "EmailAssistant-Production"
  }'

​
Configuration

ParameterTypeRequiredDescription
namestringNoThe name to display on the trace. If not specified, the default system name will be used.
For backwards compatibility, orq.name is also supported but deprecated. Use top-level name for new implementations.
Default behavior: If no name provided, system uses default identifier.

​
Naming Conventions

// Service-Environment
"UserAPI-Production";
"ChatBot-Development";

// Team-Service-Feature
"Platform-Auth-OAuth";
"ML-Recommendations-v2";

// Application-Version
"MobileApp-v3.1";
"WebPortal-v2.0";

​
Best practices

  • Use consistent patterns across team.
  • Include environment (dev/staging/prod).
  • Avoid timestamps or dynamic values.
  • Keep names under 50 characters.
  • Use alphanumeric and hyphens only.

​
Use Cases

ScenarioNaming StrategyExample
MicroservicesService-based naminguser-service, payment-api
Multi-tenantTenant identificationtenant-123, enterprise-client
A/B testingVariant trackingexperiment-A, control-group
Feature flagsFeature identificationnew-ui-beta, legacy-flow

​
Code examples

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "input": "Help me write a professional email to follow up on a job interview",
    "name": "ContentGenerator-BlogPosts"
  }'

​
Environment Management

​
Configuration by environment

const getTrackingName = (service, environment) => {
  return `${service}-${environment}`;
};

// Usage
const trackingConfig = {
  name: getTrackingName("ChatBot", process.env.NODE_ENV),
  // Results in: "ChatBot-development", "ChatBot-production"
};

​
Environment-specific examples

// Development
name: "UserAPI-Dev"

// Staging
name: "UserAPI-Staging"

// Production
name: "UserAPI-Prod"

​
Usage

​
Filtering by application

  • View requests by specific app/service.
  • Compare performance across applications.
  • Track costs per application.
  • Monitor error rates by service.

​
Metrics available

The following are available metrics available for App Tracking:
  • Request volume per application.
  • Response times by service.
  • Cost allocation by project.
  • Error patterns by environment.

​
Advanced Patterns

​
Dynamic naming

const generateTrackingName = (userId, feature) => {
  // For multi-tenant scenarios
  return `tenant-${userId}-${feature}`;
};

// Usage
name: generateTrackingName(user.id, "chat-assistant")

​
Feature flag integration

const getFeatureName = (featureFlags) => {
  const activeFeatures = Object.keys(featureFlags)
    .filter((key) => featureFlags[key])
    .join("-");

  return `app-${activeFeatures}`;
};

​
Version tracking

// Package.json version
const packageVersion = require("./package.json").version;

name: `MyApp-v${packageVersion}`

​
Troubleshooting

Names not appearing in dashboard
  • Check name follows alphanumeric + hyphens pattern.
  • Verify requests are being sent successfully.
  • Ensure name is under character limit (50 chars).
Fragmented tracking data
  • Standardize naming conventions across team.
  • Use environment variables for consistency.
  • Implement a centralized naming function.
Too many unique names
  • Avoid timestamps or random values.
  • Limit to ~50 unique names per account.
  • Use hierarchical naming instead of flat structure.

​
Monitoring

The following metrics are available for monitoring. 
const appMetrics = {
  requestsByApp: {}, // Volume per application
  costsByApp: {}, // Spending per application
  latencyByApp: {}, // Performance per application
  errorsByApp: {}, // Error rates per application
  activeApps: new Set(), // Unique applications
};

​
Analytics queries

The following queries can be answered using the above metrics.
  • Which applications use AI most?
  • What’s the cost per application?
  • Which services have highest error rates?
  • How does performance vary by application?

​
Best Practices

​
Naming standards

  • Document naming conventions for your team.
  • Use consistent separators (hyphens recommended).
  • Include environment in name for clarity.
  • Avoid special characters or spaces.

​
Example Implementation

// Centralized tracking configuration
class OrqConfig {
  static getName(service, environment = process.env.NODE_ENV) {
    return `${service}-${environment}`;
  }

  static getConfig(service) {
    return {
      name: this.getName(service),
    };
  }
}

// Usage
const orqConfig = OrqConfig.getConfig("ChatBot");
To make sure teams within an Engineering Organization align on App Tracking principles:
  • Maintain a list of approved application names.
  • Use code reviews to enforce naming standards.
  • Set up monitoring alerts for new/unexpected names.
  • Regular cleanup of unused tracking names.

​
Limitations

  • Name constraints: Alphanumeric characters and hyphens only.
  • Length limits: Maximum 50 characters per name.
  • Storage impact: Many unique names increase metadata storage.
  • Query performance: Large numbers of unique names may slow filtering.
  • No retroactive changes: Historical traces keep original names.

​
Integration Examples

​
With external monitoring systems

const prometheus = {
  histogram: (name: string, value: number, labels: Record<string, string>) => {},
  counter: (name: string, value: number, labels: Record<string, string>) => {},
}; // replace with your Prometheus client, e.g. from prom-client

// Export metrics by application
const exportMetrics = (trackingName: string, responseTime: number, cost: number) => {
  prometheus.histogram("ai_request_duration", responseTime, {
    app: trackingName,
  });
  prometheus.counter("ai_request_cost", cost, { app: trackingName });
};

​
With logging

logger.info("AI request completed", {
  trackingName: "ChatBot-Prod",
  responseTime: 1250,
  model: "gpt-4o",
  success: true,
});