Guides
Guides

Day 1: Basic Instrumentation with payi_instrument()

Suggest Edits

📋 Overview

Welcome to our 5-day learning path to onboard to Pay-i! This series is designed to progressively introduce you to Pay-i's features, starting with the simplest concepts and building toward more advanced functionalities.

Today's Goal: Learn the absolute simplest way to start tracking your GenAI calls using payi_instrument().

🚀 Getting Started

Instrument your GenAI provider calls with Pay-i to automatically track costs, manage budgets, analyze usage patterns, and much more! This guide will walk you through the complete process from creating an application to viewing your tracked events.

1️⃣ Create an Application in Pay-i Developer Portal

Before you begin coding, you'll need to set up your application and get your API key:

  1. Log in to developer.pay-i.com

  2. Select your group and click the + Create Application button in the top-right corner

  3. Enter an application name (e.g., "Learning Path Demo") and select a group

  4. Once created, click on the application's menu (three dots) and select Settings

  5. Under the API section, copy your Primary API Key for use in the next steps

Note about Groups: Each user gets their own default group that isn't shared with others. If you need to share applications with team members, you'll need to move them to a shared group. Groups help organize related applications and provide aggregated metrics.

2️⃣ Install SDK

Install the Pay-i SDK along with your AI provider's SDK:

pip install payi openai

%pip install payi openai

Note: If you have an older version of the Pay-i SDK installed, use pip install --upgrade payi to get the latest version.

3️⃣ Set API keys

Set your API keys as environment variables (recommended):

export OPENAI_API_KEY="sk-..."  # Your OpenAI API key
export PAYI_API_KEY="api-..."   # Your Pay-i API key from step 1

$env:OPENAI_API_KEY = "sk-..."  # Your OpenAI API key
$env:PAYI_API_KEY = "api-..."   # Your Pay-i API key from step 1

set OPENAI_API_KEY=sk-...  %= Your OpenAI API key            =%
set PAYI_API_KEY=api-...   %= Your Pay-i API key from step 1 =%

🔑 Core Concept: payi_instrument()

The payi_instrument() function is your entry point to enabling Pay-i's auto-instrumentation for supported GenAI providers such as OpenAI, Anthropic, Azure OpenAI, and AWS Bedrock. To learn more:

Here's a minimal example showing how to use it:

import os
from openai import OpenAI
from payi.lib.instrument import payi_instrument

# Initialize Pay-i instrumentation (automatically intercepts calls to supported providers)
payi_instrument()

# Configure OpenAI client for direct access
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# Make API calls as usual - they'll be automatically tracked!
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello, world!"}]
)

print(response.choices[0].message.content)

That's it! With just that single call to payi_instrument(), Pay-i will automatically:

  1. Intercept calls to supported GenAI providers
  2. Calculate costs and token usage
  3. Send telemetry to the Pay-i service
  4. Provide insights through the Pay-i portal

Default Use Case

When you use payi_instrument() without any additional configuration, Pay-i automatically assigns all tracked calls to a default Use Case.

The default Use Case is named after your Python module name. For example, if your code is running in a file called summarizer.py, all your GenAI calls will be assigned to a Use Case named "summarizer".

This automatic naming is great for development and getting started quickly. For production environments, however, you'll want to override this default with more meaningful Use Case names—we'll cover how to do this later in the learning path.

What are Use Cases?

Use Cases in Pay-i are a way to categorize different features or workflows in your application. Think of them as logical groupings of AI interactions that serve a specific purpose, such as:

  • "Chat Feature"
  • "Summarization Service"
  • "Document Analysis"
  • "Email Assistant"

These categorizations help organize your cost and usage data in the Pay-i portal, making it easier to understand how different parts of your application are utilizing AI services.

Note: We'll cover how to define custom Use Cases on Day 3 of this learning path.

For a deeper dive into what Use Cases represent, see the Use Cases concept page.

✅ Verification: View Your Events

After running your code, you can view your tracked events:

  1. Return to developer.pay-i.com
  2. Select your application (created in step 1)
  3. View your request activity, including costs and usage details in the dashboard
  4. Check that your calls appear under the default use case (named after your Python module)

You should see your requests listed with details about the provider, model, tokens used, and estimated costs.

➡️ Next Steps

Congratulations! You've completed the first step in instrumenting your application with Pay-i. Tomorrow in Day 2, we'll introduce the first step in customizing telemetry: tracking individual users with @ingest(user_id).

By the end of this 5-day journey, you'll have a comprehensive understanding of how to use Pay-i to monitor, manage, and optimize your GenAI usage.

💡 Additional Resources

Updated 5 days ago