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

# Configuration

> Configure the Lumina Python SDK for your environment

Configure the Lumina Python SDK.

***

## Basic Configuration

```python theme={null}
from lumina import init_lumina

lumina = init_lumina({
    "endpoint": "http://localhost:9411/v1/traces",
    "service_name": "my-service",
})
```

***

## Configuration Options

| Option              | Type | Required | Default             | Description                         |
| ------------------- | ---- | -------- | ------------------- | ----------------------------------- |
| `endpoint`          | str  | Yes      | —                   | OTLP trace endpoint URL             |
| `service_name`      | str  | No       | `"unknown-service"` | Service identifier                  |
| `api_key`           | str  | No       | —                   | Bearer token (omit for self-hosted) |
| `environment`       | str  | No       | `"live"`            | `"live"` or `"test"`                |
| `customer_id`       | str  | No       | —                   | Customer identifier                 |
| `enabled`           | bool | No       | `True`              | Enable/disable tracing              |
| `batch_size`        | int  | No       | `10`                | Max spans per export batch          |
| `batch_interval_ms` | int  | No       | `5000`              | Batch flush interval (ms)           |
| `timeout_ms`        | int  | No       | `30000`             | Export timeout (ms)                 |
| `max_retries`       | int  | No       | `3`                 | Export retry count                  |

***

## Environment-Based Configuration

All options can be set via environment variables — no code changes needed across environments:

```python theme={null}
import os
from lumina import init_lumina

lumina = init_lumina({
    "endpoint": os.environ.get("LUMINA_ENDPOINT", "http://localhost:9411/v1/traces"),
    "service_name": os.environ.get("LUMINA_SERVICE_NAME", "my-service"),
    "enabled": os.environ.get("LUMINA_ENABLED", "true").lower() != "false",
})
```

Or rely entirely on environment variables (the SDK reads them automatically):

```bash theme={null}
export LUMINA_ENDPOINT=http://localhost:9411/v1/traces
export LUMINA_SERVICE_NAME=my-service
export LUMINA_API_KEY=lumina_...        # optional
export LUMINA_ENVIRONMENT=live
```

```python theme={null}
from lumina import init_lumina

lumina = init_lumina()  # reads all LUMINA_* env vars automatically
```

***

## Environment Variables Reference

| Variable                   | Default                           | Description                    |
| -------------------------- | --------------------------------- | ------------------------------ |
| `LUMINA_ENDPOINT`          | `http://localhost:9411/v1/traces` | OTLP collector URL             |
| `LUMINA_API_KEY`           | —                                 | API key (omit for self-hosted) |
| `LUMINA_SERVICE_NAME`      | —                                 | Service name                   |
| `LUMINA_ENVIRONMENT`       | `live`                            | `live` or `test`               |
| `LUMINA_CUSTOMER_ID`       | —                                 | Customer identifier            |
| `LUMINA_ENABLED`           | `true`                            | Set to `false` to disable      |
| `LUMINA_BATCH_SIZE`        | `10`                              | Max spans per batch            |
| `LUMINA_BATCH_INTERVAL_MS` | `5000`                            | Batch flush interval           |
| `LUMINA_MAX_RETRIES`       | `3`                               | Export retry count             |
| `LUMINA_TIMEOUT_MS`        | `30000`                           | Export timeout                 |

***

## Cloud / Managed Lumina

To send traces to Lumina Cloud, set your endpoint and API key:

```python theme={null}
from lumina import init_lumina

lumina = init_lumina({
    "endpoint": "https://collector.uselumina.io/v1/traces",
    "api_key": "lumina_...",
    "service_name": "my-service",
    "environment": "live",
})
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Basic Usage" href="/docs/sdk/python/basic-usage">
    Learn basic tracing patterns
  </Card>

  <Card title="API Reference" href="/docs/sdk/python/api-reference">
    Complete API documentation
  </Card>
</CardGroup>