Getting Started Guide

This guide will help you get Monoscope running and receive your first telemetry data in 5 minutes!

Quick Start (2 minutes)

Step 1: Start Monoscope with Docker Compose

Docker Compose is the recommended way to install Monoscope as it includes all required dependencies.

# Clone and start Monoscope
git clone https://github.com/monoscope-tech/monoscope.git
cd monoscope
docker-compose up -d

# Verify services are running
docker-compose ps

Step 2: Access the UI

Open your browser and go to http://localhost:8080
Log in with default credentials:
- Username: admin
- Password: changeme

Step 3: Create Your First Project

Click "New Project" in the dashboard
Enter project details:
- Name: "My First Project"
- Description: "Testing Monoscope"
Copy the API key that's generated - you'll need it next

Send Your First Telemetry Data

Option A: Using telemetrygen (Recommended for testing)

# Install telemetrygen if you haven't
go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest

# Send test traces
telemetrygen traces \
  --otlp-endpoint localhost:4317 \
  --otlp-insecure \
  --otlp-header 'X-API-Key="YOUR_API_KEY"' \
  --traces 100 \
  --duration 10s

# Send test metrics
telemetrygen metrics \
  --otlp-endpoint localhost:4317 \
  --otlp-insecure \
  --otlp-header 'X-API-Key="YOUR_API_KEY"' \
  --metrics 5 \
  --duration 10s

# Send test logs
telemetrygen logs \
  --otlp-endpoint localhost:4317 \
  --otlp-insecure \
  --otlp-header 'X-API-Key="YOUR_API_KEY"' \
  --logs 100

Option B: Quick Python Script

# save as send_telemetry.py
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
import time

# Configure OpenTelemetry
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)

# Set up OTLP exporter
otlp_exporter = OTLPSpanExporter(
    endpoint="localhost:4317",
    insecure=True,
    headers=(("x-api-key", "YOUR_API_KEY"),)
)

# Add exporter to tracer
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(otlp_exporter)
)

# Send a test span
with tracer.start_as_current_span("test-operation") as span:
    span.set_attribute("user.id", "123")
    span.set_attribute("operation.type", "test")
    time.sleep(0.1)
    print("Telemetry sent!")

Run it:

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp
python send_telemetry.py

Option C: Using curl (Simplest)

# Send a test log entry
curl -X POST http://localhost:8080/api/v1/logs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": {
      "attributes": {
        "service.name": "test-service",
        "service.version": "1.0.0"
      }
    },
    "logs": [{
      "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)'",
      "severity": "INFO",
      "body": "Test log message from getting started",
      "attributes": {
        "user.id": "user123",
        "request.id": "req456"
      }
    }]
  }'

View Your Data

Go back to the Monoscope UI
Navigate to "Log Explorer" in the left sidebar
You should see your test data appearing
Try the natural language search: "Show all logs from test-service"

Installation Options

Docker Compose (Recommended)

The default docker-compose.yml includes everything you need:

Monoscope server
TimescaleDB with TimescaleDB extension
All necessary configuration

Prerequisites

Docker and Docker Compose installed
At least 4GB of available RAM
Ports 8080 (web UI) and 4317 (gRPC) available

Configuration

Key environment variables in docker-compose.yml:

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	Configured automatically
`PORT`	HTTP port for web UI	8080
`GRPC_PORT`	gRPC port for OpenTelemetry	4317
`BASIC_AUTH_USERNAME`	Username for basic auth	admin
`BASIC_AUTH_PASSWORD`	Password for basic auth	changeme
`SHOW_DEMO_PROJECT`	Show demo project	False

Using External Database

If you prefer to use an existing PostgreSQL/TimescaleDB instance:

Update DATABASE_URL in docker-compose.yml:

environment:
  DATABASE_URL: postgresql://user:pass@your-db-host:5432/monoscope?sslmode=require

Ensure your database has TimescaleDB extension enabled
Remove the timescaledb service from docker-compose.yml

Production Deployment

For production environments:

Use .env file for secrets

# Create .env file
cp .env.example .env
# Edit .env with your production values

Enable Auth0 for SSO

BASIC_AUTH_ENABLED: False
AUTH0_DOMAIN: your-domain.auth0.com
AUTH0_CLIENT_ID: your-client-id
AUTH0_SECRET: your-secret
AUTH0_CALLBACK: https://your-domain/auth_callback

Set resource limits

services:
  monoscope:
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 2G

Persist data volumes

volumes:
  timescale_data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/to/persistent/storage

Integrate Your Applications

Node.js Applications

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4317',
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  })
});

sdk.start();

Python Applications

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="localhost:4317",
            headers=(("x-api-key", "YOUR_API_KEY"),)
        )
    )
)

Java Applications

Add to your JVM options:

-javaagent:/path/to/opentelemetry-javaagent.jar
-Dotel.exporter.otlp.endpoint=http://localhost:4317
-Dotel.exporter.otlp.headers=x-api-key=YOUR_API_KEY
-Dotel.service.name=my-java-app

Kubernetes

See our Kubernetes Guide for deploying Monoscope on K8s and monitoring your cluster.

Explore Features

Natural Language Search

Try these example queries in the Log Explorer:

"Show me all errors in the last hour"
"What caused the spike in response time?"
"Find all database queries taking longer than 1 second"
"Show logs from the payment service"

AI Anomaly Detection

The AI anomaly detection will automatically:

Learn your system's normal behavior patterns (takes 24-48 hours)
Detect unusual patterns in logs, metrics, and traces
Group related anomalies to reduce alert noise
Send notifications through configured channels

Dashboards

Create custom dashboards by:

Navigate to "Dashboards" in the left sidebar
Click "New Dashboard"
Add widgets for metrics, logs, and traces
Customize time ranges and refresh intervals

Updating Monoscope

To update to the latest version:

# Pull latest images
docker-compose pull

# Restart services
docker-compose up -d

# Check logs for any migration messages
docker-compose logs monoscope

Troubleshooting

Not seeing data?

Check Monoscope logs:
```
docker-compose logs -f monoscope
```
Verify the endpoint is accessible:
```
telnet localhost 4317
```

Check your API key is correct:

curl http://localhost:8080/api/v1/health \
  -H "X-API-Key: YOUR_API_KEY"

Port already in use?

Change ports in docker-compose.yml:

ports:
  - "8081:8080"  # Use 8081 instead
  - "4318:4317"  # Use 4318 instead

Database connection failed?

# Check database is running
docker-compose ps timescaledb

# Check database logs
docker-compose logs timescaledb

Out of memory?

Increase Docker memory allocation:

Docker Desktop: Settings → Resources → Memory

Next Steps

Read the Configuration Reference for all options
Set up Alert Configuration for anomaly detection
Deploy on Kubernetes for production
Review the Architecture for technical details
Join our Discord community

Need Help?

💬 Discord - Chat with users and contributors
🐛 Issues - Report bugs
📝 Blog - Tutorials and case studies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting Started Guide

Quick Start (2 minutes)

Step 1: Start Monoscope with Docker Compose

Step 2: Access the UI

Step 3: Create Your First Project

Send Your First Telemetry Data

Option A: Using telemetrygen (Recommended for testing)

Option B: Quick Python Script

Option C: Using curl (Simplest)

View Your Data

Installation Options

Docker Compose (Recommended)

Prerequisites

Configuration

Using External Database

Production Deployment

Integrate Your Applications

Node.js Applications

Python Applications

Java Applications

Kubernetes

Explore Features

Natural Language Search

AI Anomaly Detection

Dashboards

Updating Monoscope

Troubleshooting

Not seeing data?

Port already in use?

Database connection failed?

Out of memory?

Next Steps

Need Help?

FilesExpand file tree

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

Getting Started Guide

Quick Start (2 minutes)

Step 1: Start Monoscope with Docker Compose

Step 2: Access the UI

Step 3: Create Your First Project

Send Your First Telemetry Data

Option A: Using telemetrygen (Recommended for testing)

Option B: Quick Python Script

Option C: Using curl (Simplest)

View Your Data

Installation Options

Docker Compose (Recommended)

Prerequisites

Configuration

Using External Database

Production Deployment

Integrate Your Applications

Node.js Applications

Python Applications

Java Applications

Kubernetes

Explore Features

Natural Language Search

AI Anomaly Detection

Dashboards

Updating Monoscope

Troubleshooting

Not seeing data?

Port already in use?

Database connection failed?

Out of memory?

Next Steps

Need Help?