Skip to content

Commit 0ab01fc

Browse files
committed
Update README.md
1 parent c1454ef commit 0ab01fc

File tree

1 file changed

+102
-22
lines changed

1 file changed

+102
-22
lines changed

README.md

Lines changed: 102 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,15 @@
1-
# OpenObserve Python SDK
1+
# OpenObserve Telemetry SDK
22

33
A simple and lightweight Python SDK for exporting OpenTelemetry logs, metrics, and traces to [OpenObserve](https://openobserve.ai/).
44

5+
## Features
6+
7+
- **Easy Integration** – Minimal setup with automatic instrumentation for popular libraries
8+
- **Multi-Signal Support** – Capture logs, metrics, and traces simultaneously
9+
- **Flexible Protocol** – Choose between HTTP/Protobuf (default) or gRPC
10+
- **Lightweight** – Minimal dependencies, designed for production use
11+
- **OpenTelemetry Native** – Built on OpenTelemetry standards for compatibility
12+
513
## Quick Start
614

715
**Generate auth token:**
@@ -12,22 +20,24 @@ echo -n "root@example.com:Complexpass#123" | base64
1220

1321
**Set environment variables:**
1422
```bash
15-
# Optional (defaults shown below)
16-
export OPENOBSERVE_URL="http://localhost:5080" # default
17-
export OPENOBSERVE_ORG="default" # default
18-
19-
# Required
23+
# OpenObserve Configuration (Required)
2024
export OPENOBSERVE_AUTH_TOKEN="Basic cm9vdEBleGFtcGxlLmNvbTpDb21wbGV4cGFzcyMxMjM="
21-
export OPENAI_API_KEY="your-api-key"
22-
export ANTHROPIC_API_KEY="your-api-key"
25+
26+
# Optional OpenObserve settings (defaults shown)
27+
export OPENOBSERVE_URL="http://localhost:5080"
28+
export OPENOBSERVE_ORG="default"
29+
30+
# API keys for services you're using (optional, based on instrumentation)
31+
export OPENAI_API_KEY="your-openai-key"
32+
export ANTHROPIC_API_KEY="your-anthropic-key"
2333
```
2434

2535
**Install dependencies:**
2636
```bash
27-
uv pip install openobserve-telemetry-sdk openai opentelemetry-instrumentation-openai
37+
pip install openobserve-telemetry-sdk openai opentelemetry-instrumentation-openai
2838
```
2939

30-
**Use with OpenAI:**
40+
**Quick Example – OpenAI Instrumentation:**
3141
```python
3242
from opentelemetry.instrumentation.openai import OpenAIInstrumentor
3343
from openobserve import openobserve_init
@@ -47,19 +57,52 @@ response = client.chat.completions.create(
4757
print(response.choices[0].message.content)
4858
```
4959

60+
**Quick Example – Anthropic Instrumentation:**
61+
```python
62+
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
63+
from openobserve import openobserve_init
64+
65+
# Initialize OpenObserve and instrument Anthropic
66+
AnthropicInstrumentor().instrument()
67+
openobserve_init()
68+
69+
from anthropic import Anthropic
70+
71+
# Use Claude as normal - traces are automatically captured
72+
client = Anthropic()
73+
response = client.messages.create(
74+
model="claude-3-5-sonnet-20241022",
75+
max_tokens=1024,
76+
messages=[{"role": "user", "content": "Hello!"}]
77+
)
78+
print(response.content[0].text)
79+
```
80+
5081
### Selecting Signals
5182

52-
`openobserve_init()` initializes logs, metrics, and traces when no signal arguments are provided. As soon as you pass any of the `logs`, `metrics`, or `traces` flags, only the explicitly provided signals are enabled.
83+
By default, `openobserve_init()` initializes all signals (logs, metrics, traces). You can also initialize selectively:
5384

5485
```python
55-
# All signals (logs + metrics + traces)
86+
# All signals (default)
5687
openobserve_init()
5788

58-
# Logs only
89+
# Specific signals only
5990
openobserve_init(logs=True)
91+
openobserve_init(metrics=True)
92+
openobserve_init(traces=True)
93+
94+
# Combine signals
95+
openobserve_init(logs=True, metrics=True) # no traces
96+
```
97+
98+
**Note:** For logs, you still need to bridge Python's standard `logging` module:
99+
```python
100+
import logging
101+
from opentelemetry.sdk._logs import LoggingHandler
60102

61-
# Logs + metrics (no traces)
62-
openobserve_init(logs=True, metrics=True)
103+
openobserve_init(logs=True)
104+
handler = LoggingHandler()
105+
logging.getLogger().addHandler(handler)
63106
```
64107

65108
## Environment Variables
@@ -97,23 +140,60 @@ openobserve_init(logs=True, metrics=True)
97140

98141
## Installation
99142

143+
Choose your preferred installation method:
144+
100145
```bash
101-
# Install from PyPI
146+
# From PyPI (recommended)
102147
pip install openobserve-telemetry-sdk
103148

104-
# Or install from source (includes both HTTP/Protobuf and gRPC support)
149+
# From source (development)
105150
pip install -e .
106151

107-
# Or using requirements.txt
152+
# Using requirements.txt
108153
pip install -r requirements.txt
109154
```
110155

156+
Both HTTP/Protobuf (default) and gRPC protocols are included in all installations.
157+
158+
## Supported Instruments
159+
160+
The SDK works with OpenTelemetry instrumentation packages:
161+
162+
- **OpenAI** – Use with `opentelemetry-instrumentation-openai` for API call traces
163+
- **Anthropic** – Use with `opentelemetry-instrumentation-anthropic` for Claude API traces
164+
- **LangChain** – Use with `opentelemetry-instrumentation-langchain` for LLM chain tracing
165+
- **Standard Python Logging** – Built-in support via `LoggingHandler`
166+
- **Metrics** – OpenTelemetry counters, histograms, and up/down counters
167+
111168
## Examples
112169

113-
- `examples/openai_example.py` – end-to-end traces example with the OpenAI instrumentation.
114-
- `examples/logs_example.py` – bridges standard Python logging through OpenTelemetry and ships the records to OpenObserve. Run with `uv run examples/logs_example.py`.
115-
- `examples/metrics_example.py` – demonstrates counters, histograms, and up/down counters exported to OpenObserve. Run with `uv run examples/metrics_example.py`.
116-
- `examples/session_demo.py`, `examples/qa_chain.py`, etc. – additional traces-first demos.
170+
Run any of these examples to see the SDK in action. First, ensure environment variables are set:
171+
172+
```bash
173+
# Traces with OpenAI
174+
python examples/openai_example.py
175+
176+
# Logs with standard Python logging
177+
python examples/logs_example.py
178+
179+
# Metrics (counters, histograms, up/down counters)
180+
python examples/metrics_example.py
181+
182+
# LangChain Q&A with session tracking
183+
python examples/session_demo.py
184+
```
185+
186+
See the `examples/` directory for more samples including LangChain RAG chains and user tracking patterns.
187+
188+
## Contributing
189+
190+
We welcome contributions! Please feel free to open issues or submit pull requests on [GitHub](https://github.com/openobserve/openobserve-python-sdk).
191+
192+
## Support
193+
194+
- 📖 [OpenObserve Documentation](https://docs.openobserve.ai/)
195+
- 🐛 [Report Issues](https://github.com/openobserve/openobserve-python-sdk/issues)
196+
- 💬 [OpenObserve Community](https://openobserve.ai/)
117197

118198
## License
119199

0 commit comments

Comments
 (0)