# Use the Opik SDK as usual

```

<Icon icon="warning" color="#DB0030" /> Make sure to add the hook before using the Opik SDK.

### TypeScript SDK Advanced Options

#### Batching Configuration

The TypeScript SDK uses batching for optimal performance. You can configure batching behavior:

```typescript
import { Opik } from "opik";

const client = new Opik({
  // Custom batching delay (default: 300ms)
  batchDelayMs: 1000,

  // Hold data until manual flush (default: false)
  holdUntilFlush: true,

  // Custom headers
  headers: {
    "Custom-Header": "value",
  },
});

// Manual flushing
await client.flush();
```

#### Global Flush Control

```typescript
import { flushAll } from "opik";

// Flush all instantiated clients
await flushAll();
```

## Configuration Reference

### Python SDK Configuration Values

| Configuration Name            | Environment Variable         | Description                                                               |
| ----------------------------- | ---------------------------- | ------------------------------------------------------------------------- |
| url\_override                 | `OPIK_URL_OVERRIDE`          | The URL of the Opik server - Defaults to `https://www.comet.com/opik/api` |
| api\_key                      | `OPIK_API_KEY`               | The API key - Only required for Opik Cloud                                |
| workspace                     | `OPIK_WORKSPACE`             | The workspace name - Only required for Opik Cloud                         |
| project\_name                 | `OPIK_PROJECT_NAME`          | The project name to use                                                   |
| opik\_track\_disable          | `OPIK_TRACK_DISABLE`         | Disable tracking of traces and spans - Defaults to `false`                |
| default\_flush\_timeout       | `OPIK_DEFAULT_FLUSH_TIMEOUT` | Default flush timeout - Defaults to no timeout                            |
| opik\_check\_tls\_certificate | `OPIK_CHECK_TLS_CERTIFICATE` | Check TLS certificate - Defaults to `true`                                |
| console\_logging\_level       | `OPIK_CONSOLE_LOGGING_LEVEL` | Console logging level - Defaults to `INFO`                                |
| file\_logging\_level          | `OPIK_FILE_LOGGING_LEVEL`    | File logging level - Not configured by default                            |
| logging\_file                 | `OPIK_LOGGING_FILE`          | File to write logs to - Defaults to `opik.log`                            |

### TypeScript SDK Configuration Values

| Configuration Name | Environment Variable    | Description                                                          |
| ------------------ | ----------------------- | -------------------------------------------------------------------- |
| apiUrl             | `OPIK_URL_OVERRIDE`     | The URL of the Opik server - Defaults to `http://localhost:5173/api` |
| apiKey             | `OPIK_API_KEY`          | The API key - Required for Opik Cloud                                |
| workspaceName      | `OPIK_WORKSPACE`        | The workspace name - Required for Opik Cloud                         |
| projectName        | `OPIK_PROJECT_NAME`     | The project name - Defaults to `Default Project`                     |
| batchDelayMs       | `OPIK_BATCH_DELAY_MS`   | Batching delay in milliseconds - Defaults to `300`                   |
| holdUntilFlush     | `OPIK_HOLD_UNTIL_FLUSH` | Hold data until manual flush - Defaults to `false`                   |
| N/A                | `OPIK_LOG_LEVEL`        | Logging level - Defaults to `INFO`                                   |
| N/A                | `OPIK_CONFIG_PATH`      | Custom config file location                                          |

## Troubleshooting

### Python SDK Troubleshooting

#### SSL Certificate Error

If you encounter the following error:

```
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1006)
```

You can resolve it by either:

* Disable the TLS certificate check by setting the `OPIK_CHECK_TLS_CERTIFICATE` environment variable to `false`
* Add the Opik server's certificate to your trusted certificates by setting the `REQUESTS_CA_BUNDLE` environment variable

#### Health Check Command

If you are experiencing problems with the Python SDK, such as receiving 400 or 500 errors from the backend, or being unable to connect at all, run the health check command:

```bash
opik healthcheck
```

This command will analyze your configuration and backend connectivity, providing useful insights into potential issues.

<Frame>
  <img src="https://files.buildwithfern.com/https://opik.docs.buildwithfern.com/docs/opik/2026-01-30T17:33:07.444Z/img/healthcheck.png" />
</Frame>

Reviewing the health check output can help pinpoint the source of the problem and suggest possible resolutions.

### TypeScript SDK Troubleshooting

#### Configuration Validation Errors

The TypeScript SDK validates configuration at startup. Common errors:

* **"OPIK\_URL\_OVERRIDE is not set"**: Set the `OPIK_URL_OVERRIDE` environment variable
* **"OPIK\_API\_KEY is not set"**: Required for Opik Cloud deployments
* **"OPIK\_WORKSPACE is not set"**: Required for Opik Cloud deployments

#### Debug Logging

Enable debug logging to troubleshoot issues:

```bash
export OPIK_LOG_LEVEL="DEBUG"
```

If you are using the Opik Optimizer SDK, you can also enable optimizer-side debug logs:

```bash
export OPIK_OPTIMIZER_LOG_LEVEL="DEBUG"
```

Or programmatically:

```typescript
import { setLoggerLevel } from "opik";
setLoggerLevel("DEBUG");
```

#### Batch Queue Issues

If data isn't appearing in Opik:

1. **Check if data is batched**: Call `await client.flush()` to force sending
2. **Verify configuration**: Ensure correct API URL and credentials
3. **Check network connectivity**: Verify firewall and proxy settings

### General Troubleshooting

#### Environment Variables Not Loading

1. **Python**: Ensure `load_dotenv()` is called before importing `opik`
2. **TypeScript**: The SDK automatically loads `.env` files
3. **Verify file location**: `.env` file should be in project root
4. **Check file format**: No spaces around `=` in `.env` files

#### Configuration File Issues

1. **File location**: Default is `~/.opik.config`
2. **Custom location**: Use `OPIK_CONFIG_PATH` environment variable
3. **File format**: Python uses TOML, TypeScript uses INI format
4. **Permissions**: Ensure file is readable by your application