Getting Started
Welcome to Qorrelate! This documentation will guide you through setting up and using
our observability platform.
Qorrelate is built on OpenTelemetry and ClickHouse, providing you with fast, scalable
observability for your applications.
Follow the steps below to get started:
- Sign up for an account
- Create or join an organization
- Create an API key for your applications
- Integrate your apps to send logs, metrics, and traces
- Start exploring your observability data
Sign Up
To get started with Qorrelate, you need to create an account. We use Auth0 for secure
authentication.
Note: If you're accessing Qorrelate for the first time, you'll be
prompted to sign up during the login process.
Steps to Sign Up:
- Click the "Sign in" or "Start Free Trial"
button on the landing page
- You'll be redirected to Auth0 for authentication
- If you don't have an account, click "Sign up" on the Auth0 page
- Enter your email address and create a password
- Complete the email verification if required
- Once authenticated, you'll be redirected back to Qorrelate
After signing up, you'll be prompted to create or select an organization.
Organizations allow you to
group your team members and manage access to your observability data.
Organizations
Organizations are the primary way to organize your team and data in Qorrelate. Each
organization has its own
API keys, members, and observability data.
Creating an Organization
When you first sign in, you'll be prompted to create an organization. You can also
create additional
organizations later from the organization dropdown in the sidebar.
To create an organization:
- Click on the organization dropdown in the top-left of the sidebar
- Click "Create organization"
- Enter a name for your organization
- Click "Create"
Once created, you'll automatically be set as a member of the organization and can
start creating API keys
and inviting team members.
Switching Organizations
If you're a member of multiple organizations, you can switch between them using the
organization dropdown
in the sidebar. All your data, API keys, and settings are scoped to the currently
selected organization.
Inviting Members to Your Organization
You can invite team members to join your organization, allowing them to access the
organization's data,
create API keys, and manage settings.
How to Invite Members:
- Click on the organization dropdown in the sidebar
- Click "Invite user"
- Enter the email address of the person you want to invite
- Click "Send Invitation"
Important: The invited user must have an Qorrelate account. If
they don't have one,
they should sign up first before accepting the invitation.
Accepting Invitations
When you receive an invitation, you'll see a notification in the organization
dropdown. Click on the
invitation to accept it and join the organization.
API Keys
API keys are used to authenticate your applications when sending logs, metrics, and
traces to Qorrelate.
Each API key is associated with an organization and can be used to send data to all
ingestion endpoints.
Security Warning: API keys provide full access to send data to
your organization.
Keep them secure and never commit them to version control. If a key is
compromised, revoke it immediately.
Creating an API Key
To create an API key for your applications:
- Navigate to Settings in the sidebar
- Go to the "API Keys" section
- Click "Create API Key"
- Enter a descriptive name for the key (e.g., "Production App", "Development
Environment")
- Optionally set an expiration date (leave blank for keys that never expire)
- Click "Create"
Important: Copy the API key immediately after creation. It will
not be shown again
for security reasons. If you lose it, you'll need to create a new key.
Using Your API Key
When you create an API key, you'll receive the following information:
- API Key: The secret key to use for authentication
- Logs Endpoint:
/v1/logs
- Metrics Endpoint:
/v1/metrics
- Traces Endpoint:
/v1/traces
Include the API key in the X-API-Key header when making
requests to these endpoints.
Integrating Your Applications
Qorrelate accepts observability data in OpenTelemetry format. You can send logs,
metrics, and traces using
standard OpenTelemetry protocols (OTLP over HTTP).
All endpoints require authentication using your API key in the X-API-Key header.
Logs Integration
Send logs to Qorrelate using the OpenTelemetry Logs Protocol (OTLP).
Endpoint
POST /v1/logs
Headers
Content-Type: application/json
X-API-Key: your-api-key-here
Request Body Format
The request body should follow the OpenTelemetry Logs Protocol format:
{
"resourceLogs": [
{
"resource": {
"attributes": [
{"key": "service.name", "value": {"stringValue": "my-service"}},
{"key": "service.version", "value": {"stringValue": "1.0.0"}}
]
},
"scopeLogs": [
{
"scope": {
"name": "my-logger"
},
"logRecords": [
{
"timeUnixNano": "1234567890000000000",
"severityText": "INFO",
"body": {
"stringValue": "Log message here"
},
"attributes": [
{"key": "log.level", "value": {"stringValue": "info"}}
]
}
]
}
]
}
]
}
Example: Using OpenTelemetry SDK
For Python applications, you can use the OpenTelemetry Python SDK:
from opentelemetry import logs
from opentelemetry.exporter.otlp.proto.http.log_exporter import OTLPLogExporter
from opentelemetry.sdk.logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk.logs.export import BatchLogRecordProcessor
# Configure exporter
exporter = OTLPLogExporter(
endpoint="https://your-qorrelate-instance.com/v1/logs",
headers={"X-API-Key": "your-api-key"}
)
# Setup logger provider
logger_provider = LoggerProvider()
logger_provider.add_log_record_processor(
BatchLogRecordProcessor(exporter)
)
logs.set_logger_provider(logger_provider)
# Use the logger
logger = logs.get_logger(__name__)
logger.info("This is a log message")
Session Replay Integration
Qorrelate Session Replay allows you to record and playback user sessions to understand
user behavior and troubleshoot issues visually.
Quick Start
Add this single line to your HTML <head>:
<script src="https://qorrelate.io/replay.js" data-api-key="your-api-key"></script>
That's it! The script automatically loads all dependencies and starts recording
sessions.
What's included: Auto-loads rrweb, persists sessions across
page reloads,
handles visibility changes, masks sensitive inputs by default, and captures
canvas content.
Configuration Options
Customize behavior with optional data attributes:
<script
src="https://qorrelate.io/replay.js"
data-api-key="your-api-key"
data-user-id="user-123" <!-- Identify user (server-rendered pages) -->
data-user-email="user@example.com"
data-mask-inputs="true" <!-- Mask sensitive inputs (default: true) -->
data-record-canvas="true" <!-- Record canvas elements (default: true) -->
data-flush-interval="5000" <!-- Send events every N ms (default: 5000) -->
data-buffer-size="50" <!-- Send when buffer reaches N events (default: 50) -->
></script>
Identifying Users
For server-rendered pages, use data attributes:
<!-- Rails/Django/PHP example -->
<script
src="https://qorrelate.io/replay.js"
data-api-key="your-api-key"
data-user-id="<%= current_user.id %>"
data-user-email="<%= current_user.email %>"
></script>
For SPAs (React, Vue, etc.), call identify after login:
// After user logs in
QorrelateReplay.identify('user-123', {
email: 'user@example.com',
plan: 'pro'
});
// Other API methods
QorrelateReplay.getSessionId(); // Get current session ID
QorrelateReplay.flush(); // Force send events now
Privacy Controls
Control what gets recorded using CSS classes:
<!-- Block entire elements from being recorded -->
<div class="qorrelate-block">This content won't be recorded</div>
<!-- Ignore specific interactions -->
<input class="qorrelate-ignore" type="text" />
ECharts & Canvas Support
If you use ECharts or other canvas-based libraries, you must ensure that any images
loaded within the canvas (e.g., background images, icons) support CORS.
- Set
crossOrigin: 'Anonymous' for any images loaded into the canvas.
- Ensure your image server sends
Access-Control-Allow-Origin: *
headers.
Without these settings, the browser will "taint" the canvas, preventing rrweb from
reading its data for security reasons.
Metrics Integration
Send metrics to Qorrelate using the OpenTelemetry Metrics Protocol (OTLP).
Endpoint
POST /v1/metrics
Headers
Content-Type: application/json
X-API-Key: your-api-key-here
Request Body Format
The request body should follow the OpenTelemetry Metrics Protocol format:
{
"resourceMetrics": [
{
"resource": {
"attributes": [
{"key": "service.name", "value": {"stringValue": "my-service"}}
]
},
"scopeMetrics": [
{
"scope": {
"name": "my-metrics"
},
"metrics": [
{
"name": "request_count",
"description": "Number of requests",
"unit": "1",
"sum": {
"dataPoints": [
{
"asInt": "100",
"timeUnixNano": "1234567890000000000",
"attributes": [
{"key": "method", "value": {"stringValue": "GET"}}
]
}
],
"aggregationTemporality": 2,
"isMonotonic": true
}
}
]
}
]
}
]
}
Example: Using Prometheus Remote
Write
You can also use Prometheus Remote Write format. Configure your Prometheus instance:
# prometheus.yml
remote_write:
- url: https://your-qorrelate-instance.com/v1/metrics
headers:
X-API-Key: your-api-key-here
Traces Integration
Send traces to Qorrelate using the OpenTelemetry Traces Protocol (OTLP).
Endpoint
POST /v1/traces
Headers
Content-Type: application/json
X-API-Key: your-api-key-here
Request Body Format
The request body should follow the OpenTelemetry Traces Protocol format:
{
"resourceSpans": [
{
"resource": {
"attributes": [
{"key": "service.name", "value": {"stringValue": "my-service"}}
]
},
"scopeSpans": [
{
"scope": {
"name": "my-tracer"
},
"spans": [
{
"traceId": "0123456789abcdef0123456789abcdef",
"spanId": "0123456789abcdef",
"name": "operation-name",
"kind": 1,
"startTimeUnixNano": "1234567890000000000",
"endTimeUnixNano": "1234567891000000000",
"attributes": [
{"key": "http.method", "value": {"stringValue": "GET"}}
],
"status": {
"code": 1
}
}
]
}
]
}
]
}
Example: Using OpenTelemetry SDK
For Python applications:
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
# Configure exporter
exporter = OTLPSpanExporter(
endpoint="https://your-qorrelate-instance.com/v1/traces",
headers={"X-API-Key": "your-api-key"}
)
# Setup tracer provider
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(tracer_provider)
# Use the tracer
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("operation-name") as span:
span.set_attribute("key", "value")
# Your code here
Protocols & Schemas
Qorrelate uses standard OpenTelemetry protocols and schemas. This ensures compatibility
with a wide range
of observability tools and libraries.
Supported Protocols
- OTLP (OpenTelemetry Protocol): Native protocol for logs,
metrics, and traces
- Prometheus Remote Write: For metrics ingestion from Prometheus
- HTTP/JSON: All endpoints accept JSON payloads over HTTP
Expected Schemas
Qorrelate expects data in OpenTelemetry format. Key attributes include:
Resource Attributes (Recommended):
service.name - Name of your serviceservice.version - Version of your serviceservice.namespace - Namespace/environment (e.g., "production",
"staging")deployment.environment - Deployment environment
Log Attributes:
log.level - Log level (DEBUG, INFO, WARN, ERROR)severityText - Severity as textseverityNumber - Severity as number (1-24)
Trace Attributes:
http.method - HTTP methodhttp.status_code - HTTP status codehttp.url - Request URLdb.system - Database system namedb.operation - Database operation
For complete schema documentation, refer to the
OpenTelemetry Specification.
