Implementation guide

Everything your team needs to connect applications, websites, mobile apps and infrastructure to Shravelle. Most teams finish in under an hour.

The process

1. Create your workspace

Go to Get started, enter your work email and company, and choose a password. You will land in your dashboard with a Production project ready. Create more projects (for example Staging) under Settings → Project.

2. Get your keys

Your keys are shown once when you register. You can create more any time under Settings → API keys.

• shv_ing_… Ingest key — for back-end services, agents and the OpenTelemetry Collector. Keep it secret.
• shv_brw_… Browser key — for websites and mobile apps. It can only send data, so it is safe to ship in your front end.
• shv_qry_… Query key — read-only API access for scripts and CI.

Your data endpoint is __INGEST__. Every SDK reads SHRAVELLE_API_KEY and SHRAVELLE_ENDPOINT from the environment.

3. Install the SDK

Pick your platform. Every SDK is built on OpenTelemetry, so popular frameworks and libraries are instrumented automatically.

Node.js

1. Install the package

npm install @shravelle/node

2. Load it first

// at the very top of your entry file (before express, pg, redis…)
require("@shravelle/node").init({ serviceName: "checkout" });

3. Start your app with your key

SHRAVELLE_API_KEY=shv_ing_xxx SHRAVELLE_ENDPOINT=__INGEST__ node app.js

Optional: richer data

const shravelle = require("@shravelle/node");
shravelle.setUser(user.id, { plan: "pro" });            // who was affected
shravelle.noticeError(err, { order_id: "123" });       // handled errors
shravelle.recordEvent("coupon_applied", { code: "DIWALI" });
app.use(shravelle.expressErrorHandler());              // after your routes

Express, Fastify, NestJS, Next.js, Koa, pg, mysql, mongodb, redis, kafkajs, axios and fetch are instrumented automatically. CPU and memory profiling is on by default.

Python

1. Install

pip install "shravelle[auto]"
opentelemetry-bootstrap -a install   # adds instrumentation for the libraries you use

2. Configure at start-up

import shravelle
shravelle.configure(service_name="checkout")

3. Run with your key

SHRAVELLE_API_KEY=shv_ing_xxx SHRAVELLE_ENDPOINT=__INGEST__ gunicorn app:app

Optional

shravelle.set_user(user.id, plan="pro")
shravelle.notice_error(exc, {"order_id": 123})
with shravelle.segment("pricing.calculate"):
    ...

Django, Flask, FastAPI, Celery, SQLAlchemy, psycopg, requests and httpx are supported. Memory profiling: set SHRAVELLE_PROFILING_MEMORY=true.

Java & Kotlin

1. Attach the agent — no code changes

SHRAVELLE_API_KEY=shv_ing_xxx SHRAVELLE_SERVICE_NAME=orders \
SHRAVELLE_ENDPOINT=__INGEST__ \
  ./shravelle-java-agent.sh java -jar app.jar

Optional API

Shravelle.noticeError(e, Map.of("order_id", "123"));
Shravelle.setUser(userId);
Shravelle.recordEvent("coupon_applied", Map.of("code", "DIWALI"));

Spring Boot, Quarkus, Micronaut, Tomcat, JDBC, Hibernate, Kafka, gRPC and HTTP clients are instrumented by the agent.

Go

1. Add the module

go get github.com/shravelle/shravelle-go

2. Start it and wrap your router

stop, err := shravelle.Start(ctx, shravelle.Config{ServiceName: "checkout"})
if err != nil { log.Fatal(err) }
defer stop(context.Background())

http.ListenAndServe(":8080", shravelle.HTTPHandler(mux, "server"))
client := shravelle.HTTPClient() // outgoing calls

3. Run with your key

SHRAVELLE_API_KEY=shv_ing_xxx SHRAVELLE_ENDPOINT=__INGEST__ ./checkout

net/http, Gin, Echo and gRPC are supported; CPU, heap and goroutine profiles are collected automatically.

.NET

1. Reference the package

<ProjectReference Include="Shravelle/Shravelle.csproj" />

2. One line in Program.cs

var builder = WebApplication.CreateBuilder(args);
builder.AddShravelle(o => o.ServiceName = "orders-api");

3. Set your key

SHRAVELLE_API_KEY=shv_ing_xxx SHRAVELLE_ENDPOINT=__INGEST__ dotnet run

ASP.NET Core, HttpClient, Entity Framework and SqlClient are instrumented.

PHP

1. Install

composer require shravelle/shravelle

2. Initialise

\Shravelle\Shravelle::init(['service' => 'shop', 'api_key' => getenv('SHRAVELLE_API_KEY'),
                        'endpoint' => getenv('SHRAVELLE_ENDPOINT')]);

Laravel / Symfony without code changes

pecl install opentelemetry
composer require open-telemetry/sdk open-telemetry/exporter-otlp open-telemetry/opentelemetry-auto-laravel
OTEL_PHP_AUTOLOAD_ENABLED=true OTEL_EXPORTER_OTLP_ENDPOINT=__INGEST__ \
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=shv_ing_xxx OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf php-fpm

WordPress: upload the Shravelle plugin, activate it, and paste your keys under Settings → Shravelle.

Ruby

1. Gemfile

gem "shravelle"

2. Initializer

# config/initializers/shravelle.rb
require "shravelle"
Shravelle.configure(service_name: "storefront")

3. Run with your key

SHRAVELLE_API_KEY=shv_ing_xxx SHRAVELLE_ENDPOINT=__INGEST__ bundle exec rails s

Rails, Sinatra, ActiveRecord, Net::HTTP and Sidekiq are supported.

Websites

1. Add the script to every page

<script src="__APP__/sdk/shravelle-browser.js"></script>
<script>
  Shravelle.init({ endpoint: "__INGEST__", key: "shv_brw_xxx", app: "my-website", release: "1.0.0" });
</script>

React / Angular / Vue (npm)

import Shravelle from "@shravelle/browser";
Shravelle.init({ endpoint: "__INGEST__", key: "shv_brw_xxx", app: "web" });
// React: wrap your app in <ShravelleErrorBoundary>; Angular: provide ShravelleErrorHandler

Use the browser key — it can only send data, never read it. Page loads, Core Web Vitals, JavaScript errors and AJAX calls are collected automatically.

Mobile apps

Android (Kotlin)

Shravelle.start(this, Shravelle.Config(endpoint = "__INGEST__", key = "shv_brw_xxx",
                                   app = "shop-android", release = BuildConfig.VERSION_NAME))
val client = OkHttpClient.Builder().addInterceptor(ShravelleInterceptor()).build()

iOS (Swift)

Shravelle.start(.init(endpoint: "__INGEST__", key: "shv_brw_xxx", app: "shop-ios"))
let session = URLSession(configuration: .shravelle)

React Native

import Shravelle from "@shravelle/react-native";
Shravelle.init({ endpoint: "__INGEST__", key: "shv_brw_xxx", app: "shop-rn" });

Flutter

void main() => Shravelle.run(
  const ShravelleConfig(endpoint: '__INGEST__', key: 'shv_brw_xxx', app: 'shop-flutter'),
  () => runApp(const MyApp()));

Crashes, app starts, screen loads and network requests are captured automatically.

Any other language (OpenTelemetry)

Any OpenTelemetry SDK works — point it at Shravelle:

export OTEL_EXPORTER_OTLP_ENDPOINT=__INGEST__
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=shv_ing_xxx"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_SERVICE_NAME=my-service

4. Linux & Windows hosts

Run the Shravelle agent on each server to collect CPU, memory, disk, network and the top processes by CPU and memory.

SHRAVELLE_ENDPOINT=__INGEST__ SHRAVELLE_API_KEY=shv_ing_xxx ./shravelle-agent
# or with Docker
docker run -d --name shravelle-agent --pid host -v /proc:/host/proc:ro \
  -e SHRAVELLE_ENDPOINT=__INGEST__ -e SHRAVELLE_API_KEY=shv_ing_xxx shravelle-agents shravelle-agent

Docker & Kubernetes

Deploy the container agent as a DaemonSet to collect node, pod and container metrics and logs. The manifest is in shravelle-deploy/k8s/agents:

kubectl create secret generic shravelle --from-literal=api-key=shv_ing_xxx
kubectl apply -f shravelle-deploy/k8s/agents/container-agent.yaml

Databases, caches and queues

List your servers in /etc/shravelle/integrations.yml on any host running the agent. You get server health, slowest queries, replication and consumer lag.

integrations:
  - type: postgres            # GRANT pg_monitor TO shravelle;
    dsn: postgres://shravelle:${PG_PASSWORD}@db.internal:5432/orders
  - type: mysql
    dsn: shravelle:${MYSQL_PASSWORD}@tcp(mysql.internal:3306)/
  - type: redis
    address: cache.internal:6379
  - type: kafka
    brokers: [kafka-1:9092]
  - type: rabbitmq
    url: http://rabbitmq.internal:15672

Supported: PostgreSQL, MySQL/MariaDB, MongoDB, Redis, Memcached, Kafka, RabbitMQ, Elasticsearch/OpenSearch, Nginx and any Prometheus /metrics endpoint.

Logs from anywhere

SDKs send your application logs automatically. For scripts and cron jobs, send a log with one request:

curl -X POST __INGEST__/v1/logs/simple -H "X-API-Key: shv_ing_xxx" \
  -H "Content-Type: application/json" \
  -d '{"level":"error","service":"backup-job","message":"backup failed: disk full"}'

5. Verify your data

1. Open your dashboard and choose the time range 15m.
2. Make a few requests to your service — it appears under Services within a minute.
3. Open Traces and Logs to see individual requests; hosts appear under Hosts.

Alerts & on-call

Three starter alerts are switched on for you: high error rate, slow responses and new errors. Under Alerts add rules for any metric, and connect email, Slack, WhatsApp, SMS, Microsoft Teams or a webhook under Settings → Notification channels. Set up rotations and escalation under On-call, and invite your team under Settings → Members with the right role.

Deployment markers

Record each deploy from CI so you can compare performance before and after a release:

curl -X POST __INGEST__/v1/deployments -H "X-API-Key: shv_ing_xxx" \
  -d '{"service":"api","version":"1.4.2","commit":"'$GIT_SHA'"}'

Get help

Stuck, or want us to do it? Request implementation — our engineers will set up Shravelle with your team, from kick-off call to handover.