> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry

> Configure anonymous usage telemetry in Graphiti

Graphiti collects anonymous usage statistics to help improve the framework. This guide explains what's collected, why, and how to disable telemetry.

## What We Collect

When you initialize a Graphiti instance, we collect:

### Anonymous Identifier

A randomly generated UUID stored locally in `~/.cache/graphiti/telemetry_anon_id`

```python theme={null}
# Example ID (generated once per machine)
"f7d8e9c0-4b3a-2c1d-9e8f-7c6b5a4d3e2f"
```

This ID:

* Is generated locally
* Is stored only on your machine
* Cannot be linked to personal information
* Is consistent across Graphiti uses on the same machine

### System Information

```python theme={null}
{
    "os": "Linux",  # Operating system
    "architecture": "x86_64",  # System architecture
    "python_version": "3.11.5"  # Python version
}
```

### Graphiti Version

```python theme={null}
"graphiti_version": "0.22.1"
```

### Configuration Choices

```python theme={null}
{
    "llm_provider": "openai",  # LLM provider type
    "database": "neo4j",  # Database backend
    "embedder": "openai"  # Embedder provider
}
```

## What We DON'T Collect

We **never** collect:

* Personal information or identifiers
* API keys or credentials
* Your actual data, queries, or graph content
* IP addresses or hostnames
* File paths or system-specific information
* Any content from your episodes, nodes, or edges
* User names or email addresses
* Database connection strings
* Model parameters or prompts

## Why We Collect This Data

This information helps us:

1. **Prioritize Provider Support**: Understand which LLM and database providers to focus development efforts on
2. **Ensure Compatibility**: Track Python versions and operating systems to maintain broad compatibility
3. **Guide Roadmap**: Identify which configurations are most popular to prioritize features
4. **Improve Quality**: Detect adoption patterns and usage trends

By sharing this anonymous information, you help make Graphiti better for the entire community.

## How Telemetry Works

### Implementation

Telemetry is implemented in `graphiti_core/telemetry/telemetry.py`:

```python theme={null}
import os
import uuid
from pathlib import Path

# PostHog configuration (public API key, safe to commit)
POSTHOG_API_KEY = 'phc_UG6EcfDbuXz92neb3rMlQFDY0csxgMqRcIPWESqnSmo'
POSTHOG_HOST = 'https://us.i.posthog.com'

# Cache directory for anonymous ID
CACHE_DIR = Path.home() / '.cache' / 'graphiti'
ANON_ID_FILE = CACHE_DIR / 'telemetry_anon_id'

def get_anonymous_id() -> str:
    """Get or create anonymous user ID."""
    if ANON_ID_FILE.exists():
        return ANON_ID_FILE.read_text().strip()
    
    # Generate new ID
    anon_id = str(uuid.uuid4())
    CACHE_DIR.mkdir(parents=True, exist_ok=True)
    ANON_ID_FILE.write_text(anon_id)
    return anon_id
```

### Telemetry Event

When Graphiti initializes:

```python theme={null}
from graphiti_core.telemetry.telemetry import capture_event

capture_event('graphiti_initialized', {
    'llm_provider': 'openai',
    'database': 'neo4j',
    'embedder': 'openai',
})
```

### Automatic Disabling

Telemetry is automatically disabled:

```python theme={null}
def is_telemetry_enabled() -> bool:
    # Disable during pytest runs
    if 'pytest' in sys.modules:
        return False
    
    # Check environment variable (default: enabled)
    env_value = os.environ.get('GRAPHITI_TELEMETRY_ENABLED', 'true').lower()
    return env_value in ('true', '1', 'yes', 'on')
```

Telemetry is disabled:

* During test runs (when `pytest` is detected)
* When explicitly disabled via environment variable

### Silent Failure

All telemetry operations fail silently:

```python theme={null}
try:
    posthog.capture(distinct_id=user_id, event=event_name, properties=properties)
except Exception:
    # Silently handle all telemetry errors
    # Never interrupt application functionality
    pass
```

Telemetry errors will never:

* Interrupt your application
* Affect Graphiti functionality
* Raise exceptions
* Appear in logs (unless debug logging is enabled)

## How to Disable Telemetry

Telemetry is **opt-out** and can be disabled at any time.

### Option 1: Environment Variable

```bash theme={null}
export GRAPHITI_TELEMETRY_ENABLED=false
```

This disables telemetry for the current shell session.

### Option 2: Shell Profile (Permanent)

Add to your shell profile for permanent disabling:

```bash theme={null}
# For bash users (~/.bashrc or ~/.bash_profile)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.bashrc
source ~/.bashrc

# For zsh users (~/.zshrc)
echo 'export GRAPHITI_TELEMETRY_ENABLED=false' >> ~/.zshrc
source ~/.zshrc

# For fish users (~/.config/fish/config.fish)
echo 'set -x GRAPHITI_TELEMETRY_ENABLED false' >> ~/.config/fish/config.fish
```

### Option 3: Python Code

Disable programmatically before importing Graphiti:

```python theme={null}
import os

# Disable telemetry
os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'

# Now import and use Graphiti
from graphiti_core import Graphiti

graphiti = Graphiti(
    "bolt://localhost:7687",
    "neo4j",
    "password"
)
```

### Option 4: .env File

Add to your `.env` file:

```bash theme={null}
# .env
GRAPHITI_TELEMETRY_ENABLED=false
```

Ensure you load the `.env` file:

```python theme={null}
from dotenv import load_dotenv

load_dotenv()  # Must be called before importing Graphiti

from graphiti_core import Graphiti
```

### Option 5: Docker Environment

For Docker deployments:

```yaml theme={null}
# docker-compose.yml
services:
  graphiti:
    image: zepai/graphiti:latest
    environment:
      - GRAPHITI_TELEMETRY_ENABLED=false
```

Or with docker run:

```bash theme={null}
docker run -e GRAPHITI_TELEMETRY_ENABLED=false zepai/graphiti:latest
```

### Option 6: Kubernetes ConfigMap

```yaml theme={null}
apiVersion: v1
kind: ConfigMap
metadata:
  name: graphiti-config
data:
  GRAPHITI_TELEMETRY_ENABLED: "false"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: graphiti-api
spec:
  template:
    spec:
      containers:
      - name: graphiti
        image: zepai/graphiti:latest
        envFrom:
        - configMapRef:
            name: graphiti-config
```

## MCP Server Telemetry

The MCP server uses Graphiti core's telemetry. Disable it the same way:

```bash theme={null}
# In mcp_server/.env
GRAPHITI_TELEMETRY_ENABLED=false
```

Or when running:

```bash theme={null}
export GRAPHITI_TELEMETRY_ENABLED=false
uv run main.py
```

## Verifying Telemetry Status

Check if telemetry is enabled:

```python theme={null}
from graphiti_core.telemetry.telemetry import is_telemetry_enabled

if is_telemetry_enabled():
    print("Telemetry is ENABLED")
else:
    print("Telemetry is DISABLED")
```

Or check the environment:

```bash theme={null}
echo $GRAPHITI_TELEMETRY_ENABLED
# Should output: false (if disabled)
```

## Viewing Your Anonymous ID

Your anonymous ID is stored locally:

```bash theme={null}
cat ~/.cache/graphiti/telemetry_anon_id
```

To reset it (generates a new ID):

```bash theme={null}
rm ~/.cache/graphiti/telemetry_anon_id
```

## Data Retention

* Telemetry data is stored by PostHog
* Data retention: 90 days for free tier
* No personally identifiable information is stored
* Data is used only for product improvement
* Data is not shared with third parties
* Data is not sold or monetized

## Privacy Policy

Graphiti respects your privacy:

1. **Opt-out**: Telemetry can be disabled at any time
2. **Anonymous**: No personal information is collected
3. **Transparent**: This documentation explains exactly what's collected
4. **Open Source**: Telemetry code is fully visible in the repository
5. **Non-intrusive**: Telemetry never affects functionality

## View the Telemetry Code

The complete telemetry implementation is open source:

```bash theme={null}
# View the source
cat graphiti_core/telemetry/telemetry.py
```

Or online: [graphiti\_core/telemetry/telemetry.py](https://github.com/getzep/graphiti/blob/main/graphiti_core/telemetry/telemetry.py)

## Technical Details

### PostHog Integration

Graphiti uses PostHog for analytics:

```python theme={null}
import posthog

posthog.api_key = POSTHOG_API_KEY  # Public key, safe to commit
posthog.host = POSTHOG_HOST

posthog.capture(
    distinct_id=anonymous_id,
    event='graphiti_initialized',
    properties={
        '$process_person_profile': False,  # Don't create user profiles
        'graphiti_version': get_graphiti_version(),
        'architecture': platform.machine(),
        # ... configuration data
    }
)
```

### Security

* Public API key is intentional (client-side analytics pattern)
* No sensitive data is transmitted
* HTTPS-only communication
* No authentication tokens
* No session tracking

### Performance Impact

* Telemetry runs asynchronously
* Single event on initialization (not per operation)
* Fails silently on error
* Minimal overhead (\< 100ms)
* No impact on core functionality

## For Enterprise Users

If you're deploying Graphiti in an enterprise environment:

1. **Review the telemetry code**: `graphiti_core/telemetry/telemetry.py`
2. **Disable if required**: Set `GRAPHITI_TELEMETRY_ENABLED=false`
3. **Network isolation**: Telemetry requires no special firewall rules (only HTTPS outbound)
4. **Compliance**: No PII collected, GDPR/CCPA compliant

## Frequently Asked Questions

### Is my data sent to Zep or third parties?

Only anonymous usage statistics are sent to PostHog (analytics provider). No actual data from your knowledge graphs is ever transmitted.

### Can I see what's being sent?

Yes! Enable debug logging:

```python theme={null}
import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('graphiti_core.telemetry')
logger.setLevel(logging.DEBUG)

from graphiti_core import Graphiti
# Telemetry events will be logged
```

### Does telemetry slow down Graphiti?

No. Telemetry:

* Runs asynchronously
* Only fires once on initialization
* Fails silently on errors
* Has minimal overhead (\< 100ms)

### What happens if I disable telemetry?

Nothing changes in functionality. Graphiti works exactly the same with telemetry disabled.

### Is telemetry required for support?

No. Telemetry is completely optional and doesn't affect support.

### Can I contribute without enabling telemetry?

Absolutely! Telemetry is automatically disabled during test runs and development.

## Contact

Questions about telemetry?

* Open an issue: [GitHub Issues](https://github.com/getzep/graphiti/issues)
* Join Discord: [Zep Discord](https://discord.com/invite/W8Kw6bsgXQ) #graphiti channel
* Email: [privacy@getzep.com](mailto:privacy@getzep.com)

## Next Steps

* [Optimize performance](/advanced/performance-tuning)
* [Build custom drivers](/advanced/custom-drivers)
* [Deploy the MCP server](/advanced/mcp-server)
* [Integrate with LangGraph](/advanced/langgraph-agents)