Skip to content

About Monocle2AI

Monocle2AI

Monocle2AI is a GenAI-native community driven open source project created to simplify instrumentation and testing of AI apps so app developers can built high impact, safe and reliable AI apps. Sandbox under Linux Foundation, Monocle2AI helps app developers make GenAI apps observable without having to write last-mile monitoring code and add reproducible tests.

Okahu AI Observability platform uses Monocle2AI to generate Otel compliant traces from application code built using any agentic framework, using any LLM inference provider or app development framework in python or typescript languages. Okahu also uses the pytest compatible framwork in Monocle2AI to capture traces generated from tests to run evaluations and assertions on those traces.

  • Contribute to Monocle2AI on Github
  • Join the Monocle2AI community on Discord

Optional: Setup Python virtual environment

python -m venv .venv
source .venv/bin/activate

Then download Monocle library releases from Pypi.

pip install monocle_apptrace
  • For Azure support (to upload traces to Azure), install with the azure extra:
pip install monocle_apptrace[azure]
  • For AWS support (to upload traces to AWS), install with the aws extra:
pip install monocle_apptrace[aws]

Development

  • You can locally build and install Monocle library from source

pip install .
- Install the optional test dependencies listed against dev in pyproject.toml in editable mode

pip install -e ".[dev]"

from monocle_apptrace import setup_monocle_telemetry
# Call the setup Monocle telemetry method
setup_monocle_telemetry(workflow_name = "simple_math_app")

Setup Environment Variables

You can export any of these variables or put them in .env file.

Name Description
AWS_ACCESS_KEY_ID AWS access key ID for authenticating with AWS services. Used by S3 exporters to access AWS resources.
AWS_SECRET_ACCESS_KEY AWS secret access key for authenticating with AWS services. Used by S3 exporters to access AWS resources.
AWS_REGION AWS region where AWS services are hosted. Used by S3 exporters and other AWS integrations. Default: us-east-1
MONOCLE_S3_BUCKET_REGION AWS region where the S3 bucket is located. Used for S3 bucket creation and configuration.
MONOCLE_S3_BUCKET_NAME Name of the S3 bucket used by Monocle for storing trace data. Default: monocle-traces
MONOCLE_BLOB_CONNECTION_STRING Azure Blob Storage connection string for authenticating with Azure Storage services. Format: DefaultEndpointsProtocol=https;AccountName=<AccountName>;AccountKey=<AccountKey>;EndpointSuffix=core.windows.net
MONOCLE_BLOB_CONTAINER_NAME Name of the Azure Blob Storage container used by Monocle for storing trace data. Default: monocle-traces
MONOCLE_EXPORTER Comma-separated list of exporters to use for trace data. Supported values: okahu, s3, blob, file, memory, console. Default: file

AWS and S3 Configuration Guide

Step-by-Step Guide to Obtain AWS and S3 Values

Assuming you already have an AWS account with S3 access, you'll need to gather the following values:

  • AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY: Your AWS credentials
  • AWS_REGION: The AWS region where your services are hosted
  • MONOCLE_S3_BUCKET_REGION: The region where your S3 bucket resides
  • MONOCLE_S3_BUCKET_NAME: The name of your S3 bucket

Steps to Obtain These Values:

1. Get AWS Credentials

  1. Sign in to the AWS Management Console
  2. Navigate to the IAM Dashboard
  3. Go to "Users" and select your existing IAM user
  4. Click on "Security credentials" tab
  5. Create a new access key if you don't have one
  6. Copy the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

For detailed instructions, refer to the AWS IAM User Guide.

2. Get AWS Region

  1. In the AWS Management Console, look at the top-right corner
  2. The current region is displayed (e.g., us-east-1, us-west-2)
  3. Use this as your AWS_REGION and MONOCLE_S3_BUCKET_REGION

For a complete list of regions, refer to the AWS Regional Services List.

3. Get S3 Bucket Name

  1. Navigate to the S3 Dashboard
  2. Find your existing S3 bucket in the list
  3. Copy the bucket name as your MONOCLE_S3_BUCKET_NAME

For more details, see the Amazon S3 User Guide.

Example Configuration

export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>"
export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>"
export AWS_REGION="us-east-1"
export MONOCLE_S3_BUCKET_REGION="us-east-1"
export MONOCLE_S3_BUCKET_NAME="monocle-traces"
export MONOCLE_EXPORTER="s3"

Azure Blob Storage Configuration Guide

Step-by-Step Guide to Obtain Azure Blob Storage Values

To configure Monocle with Azure Blob Storage, you'll need:

  • MONOCLE_BLOB_CONNECTION_STRING: The connection string for your Azure Storage account
  • MONOCLE_BLOB_CONTAINER_NAME: The name of the Blob Storage container

Steps to Obtain These Values:

1. Create an Azure Storage Account

  1. Sign in to the Azure Portal
  2. Navigate to "Storage accounts" and click on "Create"
  3. Provide the necessary details and create the storage account

For detailed instructions, refer to the Azure Storage Account Documentation.

2. Retrieve the Connection String

  1. In the Azure Portal, go to your storage account
  2. Navigate to "Access keys" under the "Security + networking" section
  3. Copy one of the connection strings provided. This will be your MONOCLE_BLOB_CONNECTION_STRING

For more details, see the Azure Storage Connection String Documentation.

3. Create a Blob Container

  1. Within your storage account, navigate to "Containers"
  2. Click on "+ Container" to create a new container
  3. Provide a name for the container (MONOCLE_BLOB_CONTAINER_NAME) and set the desired access level

For detailed instructions, refer to the Azure Blob Storage Documentation.

Example Configuration

export MONOCLE_BLOB_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=monoclestorage;AccountKey=your-account-key;EndpointSuffix=core.windows.net"
export MONOCLE_BLOB_CONTAINER_NAME="monocle-traces"
export MONOCLE_EXPORTER="blob"

Exporter Configuration

The MONOCLE_EXPORTER environment variable allows you to specify which exporters to use for trace data. You can use multiple exporters by separating them with commas.

Supported Exporters:

  • okahu: Exports traces to Okahu platform
  • s3: Exports traces to AWS S3
  • blob: Exports traces to Azure Blob Storage
  • file: Exports traces to local files (default)
  • memory: Stores traces in memory (useful for testing)
  • console: Prints traces to console (useful for debugging)

Example Multi-Exporter Configuration

export MONOCLE_EXPORTER="s3,blob,console"

This configuration will export traces to both S3 and Azure Blob Storage, while also printing them to the console for debugging purposes.

Additional Notes

  • If you don't set MONOCLE_EXPORTER, it defaults to file
  • If you don't set MONOCLE_S3_BUCKET_NAME, it defaults to default-bucket
  • If you don't set MONOCLE_BLOB_CONTAINER_NAME, it defaults to default-container
  • The AWS region can be set globally via AWS_REGION or specifically for S3 via MONOCLE_S3_BUCKET_REGION
  • Monocle also supports alternative AWS credential environment variables: MONOCLE_AWS_ACCESS_KEY_ID and MONOCLE_AWS_SECRET_ACCESS_KEY for S3-specific credentials