Project Management Guide

What is a Project?
Specifying Projects in SDK
Environment Variable Configuration
Dynamic Project Switching
Design Patterns
Best Practices
Dashboard Management

What is a Project?

A project is a mechanism for logically grouping logs in AITracer. Using projects allows you to:

Log Separation: Organize logs by environment, feature, or team
Cost Analysis: Track costs per project
Alert Configuration: Set different alert rules for each project
Access Control: Grant permissions to team members on a per-project basis

Projects are available on all plans
Project functionality is available on all plans, including Free. There is no limit on the number of projects.

Specifying Projects in SDK

Python

from aitracer import AITracer

# Specify project in constructor
tracer = AITracer(
    api_key="at-xxxx",
    project="my-chatbot-production"
)

# All subsequent logs will be recorded to this project
client = tracer.wrap_openai(OpenAI())

PHP

<?php
use AITracer\AITracer;

// Specify project in constructor
$tracer = new AITracer([
    'api_key' => 'at-xxxx',
    'project' => 'my-chatbot-production'
]);

$client = $tracer->wrapOpenAI(OpenAI::client($apiKey));

TypeScript

import { AITracer } from '@haro/aitracer';

// Specify project in constructor
const tracer = new AITracer({
  apiKey: 'at-xxxx',
  projectId: 'my-chatbot-production'
});

Environment Variable Configuration

Using environment variables allows you to switch projects per environment without changing code.

Environment Variables

Variable Name	Description	Example
`AITRACER_API_KEY`	API Key	at-xxxx...
`AITRACER_PROJECT`	Project name	my-chatbot-production

.env File Example

# Production (.env.production)
AITRACER_API_KEY=at-xxxx
AITRACER_PROJECT=my-chatbot-production

# Staging (.env.staging)
AITRACER_API_KEY=at-xxxx
AITRACER_PROJECT=my-chatbot-staging

# Development (.env.development)
AITRACER_API_KEY=at-xxxx
AITRACER_PROJECT=my-chatbot-development

Code Using Environment Variables

from aitracer import AITracer

# Automatically reads from environment variables (parameters can be omitted)
tracer = AITracer()

# Or explicitly get from environment variables
import os
tracer = AITracer(
    api_key=os.getenv("AITRACER_API_KEY"),
    project=os.getenv("AITRACER_PROJECT")
)

Recommended: Use Environment Variables
By managing project names via environment variables instead of hardcoding them, you can reuse the same code across multiple environments.

Dynamic Project Switching

You can also switch projects dynamically within the same application based on context.

Specify Project Per Request

# For manual logs, you can specify project per request
tracer.log({
    "model": "gpt-4",
    "provider": "openai",
    "project": "special-feature",  # This log goes to a different project
    "input_data": {...},
    "output_data": {...}
})

Using Multiple Tracer Instances

from aitracer import AITracer
from openai import OpenAI

# Create a Tracer for each project
tracer_chat = AITracer(project="chatbot")
tracer_search = AITracer(project="search-feature")
tracer_summary = AITracer(project="summarization")

# Use different clients for each feature
chat_client = tracer_chat.wrap_openai(OpenAI())
search_client = tracer_search.wrap_openai(OpenAI())
summary_client = tracer_summary.wrap_openai(OpenAI())

Temporarily Switch Projects with Context Manager

# Default project
tracer = AITracer(project="main-app")
client = tracer.wrap_openai(OpenAI())

# Normal request (recorded to main-app)
response = client.chat.completions.create(...)

# Temporarily change project
with tracer.project("experimental-feature"):
    # Logs in this block are recorded to experimental-feature
    response = client.chat.completions.create(...)

# Outside the block, reverts to original project
response = client.chat.completions.create(...)  # Recorded to main-app

Design Patterns

Project design methods vary depending on team size and application structure. Here are some common patterns.

Environment-based Pattern

Separate projects by environment such as development, staging, and production. The simplest and most common approach.

myapp-development
myapp-staging
myapp-production

Feature-based Pattern

Separate projects by application feature. Useful for per-feature cost analysis.

chatbot
search
summarization
translation

Team-based Pattern

Separate projects by development team. Useful for per-team budget management.

team-alpha
team-beta
team-gamma

Combined Pattern

Combine multiple dimensions like environment x feature. For large-scale projects.

chatbot-production
chatbot-staging
search-production
search-staging

Pattern Selection Guide

Situation	Recommended Pattern	Reason
Small team, single app	Environment-based	Simple and easy to manage
App with multiple features	Feature-based or Combined	Enables per-feature cost tracking
Multiple development teams	Team-based or Combined	Per-team budget management
Microservices architecture	Service + Environment	Enables per-service monitoring

Best Practices

1. Use Consistent Naming Conventions

Use a consistent naming convention for project names.

# Good example: Consistent kebab-case
my-chatbot-production
my-chatbot-staging
search-api-production

# Bad example: Inconsistent naming
MyChatBot
my_chatbot_staging
searchAPI-prod

2. Use Environment Variables

Manage project names via environment variables instead of hardcoding them.

# Bad example: Hardcoded
tracer = AITracer(project="my-chatbot-production")

# Good example: Environment variable
tracer = AITracer(project=os.getenv("AITRACER_PROJECT"))

3. Always Separate Production and Development

At minimum, keep production and development environments in separate projects.

Test logs during development won't mix with production data
Accurately track production costs and performance
Production alerts won't be triggered by development logs

4. Combine with Metadata

Use projects for broad categorization and metadata for detailed classification.

# Project: Broad categorization by app + environment
tracer = AITracer(project="chatbot-production")

# Metadata: Attach detailed attributes
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    extra_body={
        "aitracer_metadata": {
            "user_id": "user-123",
            "feature": "customer-support",
            "version": "2.1.0"
        }
    }
)

5. Set Alerts Per Project

Always configure alerts for production projects.

Notify when error rate exceeds 5%
Warn when monthly cost reaches 80% of budget
Notify when P95 latency exceeds threshold

Note on Changing Project Names
The project of recorded logs cannot be changed. If you change a project name, it will be recorded as a new project.

Dashboard Management

Creating a Project

Log in to the Dashboard
Click "Projects" in the left menu
Click "+ New Project"
Enter project name and description
Click "Create"

Project Settings

Setting	Description
Name & Description	Project identification information
Default Alerts	Alerts to auto-configure when project is created
Data Retention	Log retention period (customizable on Enterprise only)
Access Permissions	Team member access permissions

Filtering by Project

You can use projects as filters across dashboard views.

Home: View statistics by project
Logs: Filter logs by project
Analytics: Cost and performance analysis by project
Alerts: Project-specific alert rules

No Dashboard Pre-creation Required
When you specify a project name in the SDK, the project is automatically created. Pre-creation in the dashboard is not required.