> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# App tracking for AI requests

> Track LLM usage by application context. Segment AI analytics, costs, and performance metrics across different apps, features, or user segments for insights.

**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.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const response = await client.responses.create({
    model: "openai/gpt-4o-mini",
    input: "Write a professional email",
    name: "EmailAssistant-Production",
  });

  console.log(response.output_text);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from openai import OpenAI
  import os

  client = OpenAI(
      api_key=os.environ.get("ORQ_API_KEY"),
      base_url="https://api.orq.ai/v3/router",
  )

  response = client.responses.create(
      model="openai/gpt-4o-mini",
      input="Write a professional email",
      extra_body={"name": "EmailAssistant-Production"},
  )

  print(response.output_text)
  ```

  ```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const response = await client.chat.completions.create({
    model: "openai/gpt-4o-mini",
    messages: [{ role: "user", content: "Write a professional email" }],
    name: "EmailAssistant-Production",
  });
  ```

  ```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from openai import OpenAI
  import os

  client = OpenAI(
      api_key=os.environ.get("ORQ_API_KEY"),
      base_url="https://api.orq.ai/v3/router",
  )

  response = client.chat.completions.create(
      model="openai/gpt-4o-mini",
      messages=[{"role": "user", "content": "Write a professional email"}],
      extra_body={"name": "EmailAssistant-Production"},
  )
  ```
</CodeGroup>

## Configuration

| Parameter | Type   | Required | Description                                                                               |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| `name`    | string | No       | The name to display on the trace. If not specified, the default system name will be used. |

<Note>
  For backwards compatibility, `orq.name` is also supported but deprecated. Use top-level `name` for new implementations.
</Note>

**Default behavior**: If no name provided, system uses default identifier.

## Naming Conventions

### Recommended patterns

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Service-Environment
  "UserAPI-Production";
  "ChatBot-Development";

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

  // Application-Version
  "MobileApp-v3.1";
  "WebPortal-v2.0";
  ```
</CodeGroup>

### 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

| Scenario          | Naming Strategy        | Example                           |
| ----------------- | ---------------------- | --------------------------------- |
| **Microservices** | Service-based naming   | `user-service`, `payment-api`     |
| **Multi-tenant**  | Tenant identification  | `tenant-123`, `enterprise-client` |
| **A/B testing**   | Variant tracking       | `experiment-A`, `control-group`   |
| **Feature flags** | Feature identification | `new-ui-beta`, `legacy-flow`      |

## Code examples

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
    }'
  ```

  ```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v3/router/chat/completions \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o-mini",
      "messages": [
        {
          "role": "user",
          "content": "Help me write a professional email to follow up on a job interview"
        }
      ],
      "name": "ContentGenerator-BlogPosts"
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const response = await client.responses.create({
    model: "openai/gpt-4o-mini",
    input: "Help me write a professional email to follow up on a job interview",
    name: "ContentGenerator-BlogPosts",
  });

  console.log(response.output_text);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from openai import OpenAI
  import os

  client = OpenAI(
      api_key=os.environ.get("ORQ_API_KEY"),
      base_url="https://api.orq.ai/v3/router",
  )

  response = client.responses.create(
      model="openai/gpt-4o-mini",
      input="Help me write a professional email to follow up on a job interview",
      extra_body={"name": "ContentGenerator-BlogPosts"},
  )

  print(response.output_text)
  ```

  ```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const response = await client.chat.completions.create({
    model: "openai/gpt-4o-mini",
    messages: [
      {
        role: "user",
        content: "Help me write a professional email to follow up on a job interview",
      },
    ],
    name: "ContentGenerator-BlogPosts",
  });
  ```

  ```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from openai import OpenAI
  import os

  client = OpenAI(
      api_key=os.environ.get("ORQ_API_KEY"),
      base_url="https://api.orq.ai/v3/router",
  )

  response = client.chat.completions.create(
      model="openai/gpt-4o-mini",
      messages=[
          {
              "role": "user",
              "content": "Help me write a professional email to follow up on a job interview",
          }
      ],
      extra_body={"name": "ContentGenerator-BlogPosts"},
  )
  ```
</CodeGroup>

## Environment Management

### Configuration by environment

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const getTrackingName = (service, environment) => {
    return `${service}-${environment}`;
  };

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

### Environment-specific examples

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Development
  name: "UserAPI-Dev"

  // Staging
  name: "UserAPI-Staging"

  // Production
  name: "UserAPI-Prod"
  ```
</CodeGroup>

## AI Studio Integration

### 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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const generateTrackingName = (userId, feature) => {
    // For multi-tenant scenarios
    return `tenant-${userId}-${feature}`;
  };

  // Usage
  name: generateTrackingName(user.id, "chat-assistant")
  ```
</CodeGroup>

### Feature flag integration

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const getFeatureName = (featureFlags) => {
    const activeFeatures = Object.keys(featureFlags)
      .filter((key) => featureFlags[key])
      .join("-");

    return `app-${activeFeatures}`;
  };
  ```
</CodeGroup>

### Version tracking

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Package.json version
  const packageVersion = require("./package.json").version;

  name: `MyApp-v${packageVersion}`
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const appMetrics = {
    requestsByApp: {}, // Volume per application
    costsByApp: {}, // Spending per application
    latencyByApp: {}, // Performance per application
    errorsByApp: {}, // Error rates per application
    activeApps: new Set(), // Unique applications
  };
  ```
</CodeGroup>

### 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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // 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");
  ```
</CodeGroup>

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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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 });
  };
  ```
</CodeGroup>

### With logging

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  logger.info("AI request completed", {
    trackingName: "ChatBot-Prod",
    responseTime: 1250,
    model: "gpt-4o",
    success: true,
  });
  ```
</CodeGroup>