feat: Universal auto-instrumentation for all languages
## New Features ### Universal Instrumentation Container - Created deploy/instrumentation/ with Dockerfile that downloads OTel agents for: - .NET (glibc and musl/Alpine versions) - Node.js (with auto-instrumentation package) - Python (bootstrap script + requirements) - Java (javaagent JAR) - Go (example code for compile-time instrumentation) - PHP (composer package + init script) ### Universal instrument.sh Script - Auto-detects application language from running processes - Generates docker-compose snippets for each language - Supports: dotnet, nodejs, python, java, go, php - Usage: ./instrument.sh <container> [language] [otlp_endpoint] ### Improved docker-compose.yml - Added instrumentation init container with shared volume - Added AGENT_KEY environment variable for proper auth - Added ophion-agent service for host metrics collection - Named containers for easier management - Added ophion-network for service discovery ### Documentation - Created docs/QUICK_START.md with: - Single-command installation - Instrumentation guide for all languages - Troubleshooting section - Authentication guide ### Auth Fixes - Server now properly validates AGENT_KEY for agent authentication - OTel Collector configured with AGENT_KEY for forwarding to server - Fixed 401 errors when agents connect ## Files Changed - docker-compose.yml: Complete stack with all services - deploy/instrumentation/*: Universal OTel agent container - deploy/docker/otel-collector-config.yaml: Fixed auth headers - instrument.sh: Universal instrumentation script - docs/QUICK_START.md: Complete quick start guide - README.md: Updated with new features - .env.example: Added AGENT_KEY ## Testing - Go code compiles successfully - Docker images build correctly - All changes are backwards compatible
This commit is contained in:
347
docs/QUICK_START.md
Normal file
347
docs/QUICK_START.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# 🐍 OPHION - Quick Start Guide
|
||||
|
||||
Get full observability (traces, metrics, logs) for your applications in minutes.
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
- Docker & Docker Compose v2+
|
||||
- 4GB RAM minimum
|
||||
- Ports available: 3000, 4317, 4318, 8080
|
||||
|
||||
---
|
||||
|
||||
## 🚀 1. Install Ophion (Single Command)
|
||||
|
||||
```bash
|
||||
# Clone and start
|
||||
git clone https://github.com/bigtux/ophion.git
|
||||
cd ophion
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
That's it! Wait ~2 minutes for all services to start.
|
||||
|
||||
### Verify Installation
|
||||
|
||||
```bash
|
||||
# Check all services are running
|
||||
docker compose ps
|
||||
|
||||
# Should see:
|
||||
# ophion-server running (healthy)
|
||||
# ophion-dashboard running
|
||||
# ophion-otel-collector running (healthy)
|
||||
# ophion-postgres running (healthy)
|
||||
# ophion-redis running (healthy)
|
||||
```
|
||||
|
||||
### Access Points
|
||||
|
||||
| Service | URL | Description |
|
||||
|---------|-----|-------------|
|
||||
| Dashboard | http://localhost:3000 | Web UI for traces, metrics, logs |
|
||||
| API | http://localhost:8080 | REST API |
|
||||
| OTLP gRPC | localhost:4317 | OpenTelemetry gRPC endpoint |
|
||||
| OTLP HTTP | localhost:4318 | OpenTelemetry HTTP endpoint |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 2. Instrument Your Application
|
||||
|
||||
### Quick Method: Use the Universal Script
|
||||
|
||||
```bash
|
||||
# Auto-detect language
|
||||
./instrument.sh my-container
|
||||
|
||||
# Or specify language
|
||||
./instrument.sh my-container nodejs
|
||||
./instrument.sh my-container python
|
||||
./instrument.sh my-container java
|
||||
./instrument.sh my-container dotnet
|
||||
```
|
||||
|
||||
### Manual Configuration by Language
|
||||
|
||||
#### Node.js
|
||||
|
||||
```dockerfile
|
||||
# Dockerfile
|
||||
FROM node:20-alpine
|
||||
|
||||
# Add OTel packages
|
||||
RUN npm install @opentelemetry/auto-instrumentations-node @opentelemetry/sdk-node
|
||||
|
||||
COPY . .
|
||||
|
||||
# Run with auto-instrumentation
|
||||
CMD ["node", "--require", "@opentelemetry/auto-instrumentations-node/register", "app.js"]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
myapp:
|
||||
environment:
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion-otel-collector:4318
|
||||
- OTEL_SERVICE_NAME=my-nodejs-app
|
||||
networks:
|
||||
- ophion-network
|
||||
|
||||
networks:
|
||||
ophion-network:
|
||||
external: true
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
```dockerfile
|
||||
# Dockerfile
|
||||
FROM python:3.11-slim
|
||||
|
||||
RUN pip install opentelemetry-distro opentelemetry-exporter-otlp
|
||||
RUN opentelemetry-bootstrap -a install
|
||||
|
||||
COPY . .
|
||||
|
||||
CMD ["opentelemetry-instrument", "python", "app.py"]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
myapp:
|
||||
environment:
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion-otel-collector:4318
|
||||
- OTEL_SERVICE_NAME=my-python-app
|
||||
- OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
|
||||
networks:
|
||||
- ophion-network
|
||||
```
|
||||
|
||||
#### Java
|
||||
|
||||
```dockerfile
|
||||
# Dockerfile
|
||||
FROM eclipse-temurin:21-jre
|
||||
|
||||
# Download OTel Java agent
|
||||
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar /otel/agent.jar
|
||||
|
||||
COPY target/app.jar /app.jar
|
||||
|
||||
CMD ["java", "-javaagent:/otel/agent.jar", "-jar", "/app.jar"]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
myapp:
|
||||
environment:
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion-otel-collector:4318
|
||||
- OTEL_SERVICE_NAME=my-java-app
|
||||
- JAVA_TOOL_OPTIONS=-javaagent:/otel/agent.jar
|
||||
networks:
|
||||
- ophion-network
|
||||
```
|
||||
|
||||
#### .NET
|
||||
|
||||
```dockerfile
|
||||
# Dockerfile
|
||||
FROM mcr.microsoft.com/dotnet/aspnet:8.0
|
||||
|
||||
# Download OTel .NET instrumentation
|
||||
ADD https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/opentelemetry-dotnet-instrumentation-linux-glibc-x64.zip /tmp/otel.zip
|
||||
RUN apt-get update && apt-get install -y unzip && \
|
||||
unzip /tmp/otel.zip -d /otel && rm /tmp/otel.zip
|
||||
|
||||
COPY --from=build /app/publish .
|
||||
|
||||
ENV CORECLR_ENABLE_PROFILING=1
|
||||
ENV CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658571}
|
||||
ENV CORECLR_PROFILER_PATH=/otel/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
|
||||
ENV DOTNET_ADDITIONAL_DEPS=/otel/AdditionalDeps
|
||||
ENV DOTNET_SHARED_STORE=/otel/store
|
||||
ENV DOTNET_STARTUP_HOOKS=/otel/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
|
||||
ENV OTEL_DOTNET_AUTO_HOME=/otel
|
||||
|
||||
CMD ["dotnet", "MyApp.dll"]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
myapp:
|
||||
environment:
|
||||
- OTEL_EXPORTER_OTLP_ENDPOINT=http://ophion-otel-collector:4318
|
||||
- OTEL_SERVICE_NAME=my-dotnet-app
|
||||
networks:
|
||||
- ophion-network
|
||||
```
|
||||
|
||||
#### Go
|
||||
|
||||
Go requires code changes (compile-time instrumentation):
|
||||
|
||||
```go
|
||||
import (
|
||||
"go.opentelemetry.io/otel"
|
||||
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
|
||||
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// Initialize tracer
|
||||
exporter, _ := otlptracehttp.New(context.Background())
|
||||
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
|
||||
otel.SetTracerProvider(tp)
|
||||
|
||||
// Wrap HTTP handlers
|
||||
http.Handle("/", otelhttp.NewHandler(myHandler, "myHandler"))
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 3. View Your Data
|
||||
|
||||
### Dashboard
|
||||
|
||||
Open http://localhost:3000 in your browser.
|
||||
|
||||
**Default Login:**
|
||||
- Email: `admin@ophion.io`
|
||||
- Password: `OphionAdmin123!`
|
||||
|
||||
### API Examples
|
||||
|
||||
```bash
|
||||
# Get traces
|
||||
curl http://localhost:8080/api/v1/traces \
|
||||
-H "Authorization: Bearer <your-token>"
|
||||
|
||||
# Get metrics
|
||||
curl "http://localhost:8080/api/v1/metrics?service=my-app&name=http.request.duration" \
|
||||
-H "Authorization: Bearer <your-token>"
|
||||
|
||||
# Get logs
|
||||
curl "http://localhost:8080/api/v1/logs?service=my-app&level=error" \
|
||||
-H "Authorization: Bearer <your-token>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Authentication
|
||||
|
||||
### For the Dashboard (Users)
|
||||
|
||||
Register and login at http://localhost:3000
|
||||
|
||||
### For Applications (OTLP)
|
||||
|
||||
Applications send telemetry to the **otel-collector** (ports 4317/4318) which doesn't require auth by default.
|
||||
|
||||
### For the API (Agents)
|
||||
|
||||
Use the `AGENT_KEY` environment variable:
|
||||
|
||||
```bash
|
||||
# Default key (change in production!)
|
||||
AGENT_KEY=ophion-secret-agent-key-2024
|
||||
|
||||
# Custom key
|
||||
export AGENT_KEY=my-super-secret-key
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `AGENT_KEY` | `ophion-secret-agent-key-2024` | Key for agent authentication |
|
||||
| `JWT_SECRET` | `ophion-jwt-secret-...` | Secret for JWT tokens |
|
||||
| `DATABASE_URL` | `postgres://...` | PostgreSQL connection |
|
||||
| `REDIS_URL` | `redis://redis:6379` | Redis connection |
|
||||
|
||||
Create a `.env` file in the project root:
|
||||
|
||||
```env
|
||||
AGENT_KEY=my-production-key-here
|
||||
JWT_SECRET=my-production-jwt-secret
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker Network
|
||||
|
||||
Your instrumented applications need to be on the same network as Ophion:
|
||||
|
||||
```yaml
|
||||
# Your app's docker-compose.yml
|
||||
networks:
|
||||
ophion-network:
|
||||
external: true
|
||||
```
|
||||
|
||||
Or connect manually:
|
||||
|
||||
```bash
|
||||
docker network connect ophion-network my-container
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### No traces appearing?
|
||||
|
||||
1. Check collector logs:
|
||||
```bash
|
||||
docker logs ophion-otel-collector
|
||||
```
|
||||
|
||||
2. Verify network connectivity:
|
||||
```bash
|
||||
docker exec my-container curl http://ophion-otel-collector:4318/v1/traces
|
||||
```
|
||||
|
||||
3. Check environment variables are set:
|
||||
```bash
|
||||
docker exec my-container env | grep OTEL
|
||||
```
|
||||
|
||||
### Container can't reach collector?
|
||||
|
||||
Make sure your container is on the `ophion-network`:
|
||||
|
||||
```bash
|
||||
docker network connect ophion-network my-container
|
||||
```
|
||||
|
||||
### Server returns 401?
|
||||
|
||||
Check `AGENT_KEY` matches in server and agent:
|
||||
|
||||
```bash
|
||||
docker exec ophion-server env | grep AGENT_KEY
|
||||
docker exec ophion-agent env | grep OPHION_API_KEY
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Next Steps
|
||||
|
||||
- Read [MANUAL_COMPLETO.md](./MANUAL_COMPLETO.md) for advanced configuration
|
||||
- Set up alerts at `/alerts` in the dashboard
|
||||
- Configure AI insights with your OpenAI key
|
||||
- Deploy to production with proper secrets
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Support
|
||||
|
||||
- Issues: https://github.com/bigtux/ophion/issues
|
||||
- Docs: https://ophion.io/docs
|
||||
Reference in New Issue
Block a user