Reference¶

Look-up facts for Monoscope and its storage engine TimeFusion: release history, editions and pricing, ports, environment variables, the telemetry table schema, CLI and MCP surfaces, SDK packages, access roles, and a hardening checklist. For why things work this way, see Explanation. For step-by-step tasks, see How-to Guides.

Source of truth

Values below come from the upstream repositories (monoscope-tech/monoscope README, docs/*.md, src/System/Config.hs, .env.example, docker-compose.yml; monoscope-tech/timefusion README, DELTA_CONFIG.md, RUNBOOK.md, schemas/), the GitHub releases feed, and the monoscope.tech pricing page, as read on 2026-09-25. Both projects are pre-1.0 and change quickly; confirm against the linked files before depending on a default.

Release History¶

Monoscope publishes GitHub releases (vMAJOR.MINOR.PATCH) with no separate CHANGELOG file. The Haskell package version in monoscope.cabal stays at 0.1.0.0 and does not track releases.

Release	Date (UTC)	Notable content
v0.6.27	2026-09-07	Weekly emails expanded into system reports; bounded embedding requests; CLI severity-filter fix
v0.6.26	2026-09-06	Dashboard widgets, log-list improvements, service-map layout fixes, monitor aggregate evaluation
v0.6.25	2026-08-07	Billing changes, metric service-name extraction fixes, dashboard query tuning for the TimeFusion backend
v0.6.24	2026-06-29	Kafka dead-letter (DLQ) replay consumer, CLI lifecycle work, exact-timestamp log lookups, Prometheus scraping
v0.6.23	2026-06-11	Schema learning, i18n (English/Spanish), ingestion performance work
v0.6.22	2026-05-05	CLI JSON output keeps numeric and boolean types
v0.6.21	2026-05-04	`send-event` and `telemetrygen` CLI commands
v0.6.20	2026-05-03	MCP server at `/api/v1/mcp`, CLI agent-mode hardening
v0.6.18 to v0.6.19	2026-05-01 to 2026-05-02	CI moved to Blacksmith runners, dependency updates

Source: GitHub releases feed. Cadence in 2026 has been irregular: bursts of daily releases, then gaps of 3 to 6 weeks.

TimeFusion has no tagged releases. Cargo.toml says version = "0.1.0", and container images are published per commit to ghcr.io/monoscope-tech/timefusion, tagged with the git short SHA.

Editions and Pricing¶

Edition	License	Price (2026-09)	Included	Retention
Self-hosted Community	AGPL-3.0	Free	Full source. Basic email alerts, DIY auth/SSO (README comparison)	Your storage
Self-hosted Enterprise	Commercial	Custom (contact sales)	Commercial licence, contact `[email protected]`	Your storage
Cloud	Proprietary SaaS	Free tier, then $29/month	20M events/month, then $1 per additional million	30 days
Cloud + S3 (BYOS)	Proprietary SaaS	From $199/month	100M events/month, then $1 per additional million	Unlimited (data in your bucket)

Source: monoscope.tech/pricing (read via search snippets because the site blocks automated fetches). Worked example from the pricing page: 50M events/month on Cloud = $29 + 30 x $1 = $59.

README and pricing page disagree on Cloud storage

The repository README's "Cloud vs Self-hosted" table says both options store data in your S3 buckets. The pricing page separates plain Cloud (30-day retention on Monoscope storage) from Cloud + S3 (BYOS). Treat the pricing page as authoritative for billing.

Ports and Endpoints¶

Port / path	Component	Purpose
`8080` (`PORT`)	Monoscope	Web UI, REST API, MCP endpoint
`4317` (`GRPC_PORT`)	Monoscope	OTLP/gRPC ingestion (logs, traces, metrics)
`/api/v1/mcp`	Monoscope	MCP server (HTTP JSON-RPC 2.0, protocol `2025-06-18`)
`https://api.monoscope.tech`	Monoscope Cloud	Default `MONOSCOPE_API_URL` for the CLI and MCP clients
`5432`	TimescaleDB (compose)	Metadata and the legacy telemetry store
`5432` (`PGWIRE_PORT`)	TimeFusion	PostgreSQL wire protocol (SQL reads and writes)
`5050`	pgAdmin (compose `dev` profile)	Optional DB admin UI

The compose file maps TimescaleDB and TimeFusion to the same default port. Run them on different hosts or remap one.

Monoscope Environment Variables¶

Monoscope reads all configuration from environment variables through System.Config.EnvConfig (the envy library derives names from record fields). The table lists the variables used most often. See docs/configuration.md and .env.example for the rest.

Key Environment Variables¶

Variable	Default	Purpose
`DATABASE_URL`	none (required)	PostgreSQL/TimescaleDB connection string (libpq key=value or URI form)
`TIMEFUSION_PG_URL`	none	Connection string for TimeFusion over pgwire
`PORT` / `GRPC_PORT`	`8080` / `4317`	HTTP and OTLP/gRPC listeners
`HOST_URL`	`http://localhost:8080`	Public URL of the instance
`API_KEY_ENCRYPTION_SECRET_KEY`	none	Encrypts stored project API keys. Use 32+ random characters
`MIGRATE_AND_INITIALIZE_ON_START` / `MIGRATIONS_DIR`	`True` / `./static/migrations/`	Run SQL migrations at boot
`BASIC_AUTH_ENABLED` / `_USERNAME` / `_PASSWORD`	`True` / `admin` / `changeme` (compose)	Built-in basic auth for self-hosting
`AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_SECRET`, `AUTH0_CALLBACK`, `AUTH0_LOGOUT_REDIRECT`	none	Auth0 SSO instead of basic auth
`ENABLE_TIMEFUSION_READS` / `ENABLE_TIMEFUSION_WRITES`	off	Route telemetry queries/writes to TimeFusion
`ENABLE_POSTGRES_TELEMETRY_WRITES`	`True`	Dual-write telemetry to the legacy Postgres `otel_logs_and_spans` table
`KAFKA_BROKERS`, `KAFKA_TOPICS`, `KAFKA_GROUP_ID`, `KAFKA_USERNAME`, `KAFKA_PASSWORD`	none	Optional Kafka ingestion queue (also selects the Live Tail transport)
`ENABLE_KAFKA_SERVICE` / `ENABLE_PUBSUB_SERVICE`	off in compose	Run the Kafka or Google Pub/Sub consumers
`CONSUMER_ONLY`	off	Run only the queue consumers and extraction pipeline (ingest-only instance)
`ENABLE_OTLP_GRPC_SERVICE`	`True`	Bind the gRPC OTLP listener
`ENABLE_BACKGROUND_JOBS` / `MAX_CONCURRENT_JOBS`	`True` / `4`	odd-jobs background workers
`OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`, `OPENAI_SMALL_MODEL`	model defaults are OpenAI GPT models	LLM backend for natural-language queries, agents and issue analysis. Any OpenAI-compatible endpoint
`S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_REGION`	none	S3/MinIO client settings in the Monoscope server itself (separate from TimeFusion's `AWS_*` settings). Which features use it is not documented; session-replay blobs are a likely consumer (unverified)
`ENABLE_SESSION_REPLAY` / `ENABLE_REPLAY_SERVICE` / `ENABLE_BROWSER_MONITORING`	varies	Browser SDK, RUM and replay pipeline
`SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_SENDER`, `SENDGRIDAPIKEY`, `POSTMARK_TOKEN`	none	Email delivery for alerts and reports
`SLACK_`, `DISCORD_`, `TWILIO_` / `WHATSAPP_`, `GITHUB_APP_*`	none	Slack, Discord and WhatsApp bots and alert channels, GitHub sync
`LOGGING_DESTINATION` / `LOG_LEVEL`	`StdOut` / `info`	Server logging

Variable names are derived, not hand-listed

Names such as ENABLE_TIMEFUSION_READS and S3_BUCKET are the upper-snake-case form of the EnvConfig record fields in src/System/Config.hs. That file is authoritative when docs/configuration.md lags behind it.

TimeFusion Configuration¶

TimeFusion is configured only through environment variables (src/config.rs holds the defaults, DELTA_CONFIG.md is the full list).

Variable	Default	Purpose
`AWS_S3_BUCKET`	required	Bucket that holds the Delta tables
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_DEFAULT_REGION`	none	S3 credentials
`AWS_S3_ENDPOINT`	`https://s3.amazonaws.com`	Override for MinIO, R2 and other S3-compatible stores
`AWS_ALLOW_HTTP`	unset	`true` allows plain HTTP (local MinIO)
`PGWIRE_PORT` / `PGWIRE_USER` / `PGWIRE_PASSWORD`	`5432` / `postgres` / required	pgwire listener and credentials. Startup fails without a password
`TIMEFUSION_ALLOW_INSECURE_AUTH`	`false`	Skip the password check (local development only)
`TIMEFUSION_DATA_DIR`	`./data`	Holds the WAL (`/wal`) and the disk cache (`/cache`)
`TIMEFUSION_TABLE_PREFIX`	`timefusion`	Path prefix for tables in the bucket
`TIMEFUSION_WAL_FSYNC_MODE`	`sync_each`	`sync_each`, `ms` or `none`
`TIMEFUSION_STOP_GRACE_SECS`	`70`	Graceful-shutdown budget

TimeFusion Cache Tuning¶

Parameter	Variable	Default
Write buffer ceiling	`TIMEFUSION_BUFFER_MAX_MEMORY_MB`	4096 MB
Flush interval	`TIMEFUSION_FLUSH_INTERVAL_SECS`	300 s
Buffer retention	`TIMEFUSION_BUFFER_RETENTION_MINS`	70 min
Foyer memory cache (L1)	`TIMEFUSION_FOYER_MEMORY_MB`	1024 MB
Foyer disk cache (L2)	`TIMEFUSION_FOYER_DISK_GB`	500 GB
Cache entry TTL	`TIMEFUSION_FOYER_TTL_SECONDS`	604800 s (7 days)
DataFusion memory pool	`TIMEFUSION_MEMORY_LIMIT_GB` / `TIMEFUSION_MEMORY_POOL`	8 GB / `greedy`

Compression and Compaction Tiers¶

Tier	ZSTD level	Compaction target	Schedule (6-field cron)
Hot (today)	3	32 MB files	Every 5 min (`TIMEFUSION_LIGHT_OPTIMIZE_SCHEDULE`)
Warm	9	256 MB files, 48 h window	Every 30 min (`TIMEFUSION_OPTIMIZE_SCHEDULE`)
Cold (older than 1 day for consolidation, 14 days for recompression)	19	512 MB files	Consolidation 02:30, recompression 03:00 daily
VACUUM	n/a	Retains removed files 24 h	Every 6 h

Telemetry Table Schema¶

Logs and spans share one table, otel_logs_and_spans. TimeFusion defines it in schemas/otel_logs_and_spans.yaml. The legacy Postgres store has a table of the same name.

Column	Type (TimeFusion)	Notes
`project_id`	Utf8	Tenant key and first partition column. Every query must filter on it
`date`	Date32	Second partition column. A `timestamp` range filter is turned into a `date` filter automatically
`timestamp`, `observed_timestamp`, `start_time`, `end_time`	Timestamp (microseconds, UTC)	Event times
`id`, `parent_id`	Utf8	Event or span id
`name`, `kind`, `level`, `status_code`, `status_message`	Utf8	Span name/kind, log level, status
`duration`	Int64	Nanoseconds
`hashes`, `summary`	List(Utf8)	Lookup hashes, pre-rendered summary
`body`, `attributes`, `resource`, `context`, `events`, `links`	Variant	Semi-structured OTel payloads
`attributes___http___response___status_code`, `resource___service___name`, and more	typed	OTel attributes flattened with a triple-underscore separator
`updated_at`, `deleted`	Timestamp / Boolean	Merge-on-read version and tombstone columns

Deduplication keys are timestamp, resource___service___name and id, with updated_at as the tie-breaker.

Query Languages¶

Surface	Language	Example
Web UI log explorer, CLI, REST, MCP	KQL-style query language (Megaparsec parser in `Pkg/Parser`)	`severity.severity_text=="error"`, `summarize count() by resource.service.name`
Natural language	English prompt translated to KQL by the LLM query planner	"Show me all errors in the payment service in the last hour"
TimeFusion direct	PostgreSQL-dialect SQL on DataFusion	`SELECT ... FROM otel_logs_and_spans WHERE project_id = '...'`

CLI Reference¶

Install with curl https://monoscope.tech/install.sh | sh (Linux/macOS, x86_64/arm64, installs to ~/.local/bin).

Command group	Purpose
`auth login` / `auth status` / `auth logout`	Browser or `--token` login
`config init` / `config set` / `config get`	Keys `api_url`, `project`, `api_key`
`events` / `logs` / `traces search`, `get`, `tail`, `context`	Search, fetch, live-tail, surrounding-window view
`metrics query` / `metrics chart`	KQL aggregations, `--assert` for CI gates
`monitors`, `dashboards` (`apply`, YAML round-trip)	Alerting and dashboards as code
`issues`, `log-patterns`, `endpoints`	Triage, pattern review, API catalog
`api-keys`, `members`, `teams`, `share-links`, `project`	Administration
`schema`, `facets`	Discover fields and their top values
`send-event`, `telemetrygen`	Generate test telemetry

Global flag / variable	Effect
`--project/-p`, `MONOSCOPE_PROJECT`	Project UUID
`--json` / `--yaml` / `--table`	Output format. JSON is forced when stdout is piped
`MONOSCOPE_API_KEY`, `MONOSCOPE_API_URL`	Credentials and endpoint (self-hosted: point at your host)
`MONOSCOPE_AGENT_MODE=1` or `--agent`	JSON output, no prompts. Auto-detected when `CI` or `CLAUDE_CODE` is set

Config precedence: ~/.config/monoscope/config.yaml, then .monoscope.yaml (searched up from the working directory), then environment variables.

MCP Server¶

Item	Value
Endpoint	`POST <host>/api/v1/mcp` (Cloud: `https://api.monoscope.tech/api/v1/mcp`)
Auth	`Authorization: Bearer <api-key>`. Missing or invalid key returns `401`
Methods	`initialize`, `tools/list`, `tools/call`, `notifications/*`
Tools	Every public REST route as a verb-first tool (`search_events`, `list_monitors`, `mute_monitor`, and more) plus composites `find_error_patterns`, `search_events_nl`, `analyze_issue`
Limits	30 s per tool call. Text content truncated at 64 KB (full JSON in `structuredContent`)

SDKs and Packages¶

Monoscope accepts plain OpenTelemetry, so any OTel SDK works. The vendor SDKs add request/response body capture, redaction and error reporting on top of OTel.

Language	Package / module	Repository
Python (Flask, Django, FastAPI, Pyramid)	`monoscope-flask`, `monoscope-django`, `monoscope-fastapi` on PyPI	monoscope-python
Node.js (Express, Fastify, NestJS, AdonisJS, Next.js)	`@monoscopetech/express` and siblings on npm	monoscope-js
Go (native, Gin, Echo, Fiber, Chi, Gorilla)	`github.com/monoscope-tech/monoscope-go/<framework>`	monoscope-go
Browser (RUM, session replay, web vitals)	`@monoscopetech/browser`	monoscope-web
PHP (Laravel)	see repository	monoscope-laravel
Java, .NET, Elixir	`apitoolkit-*` repositories from the APItoolkit era, or plain OTel agents	apitoolkit-springboot, apitoolkit-dotnet, apitoolkit-phoenix

Archived per-framework repositories

apitoolkit-flask, apitoolkit-django and apitoolkit-express are archived. Their code moved into the language monorepos, and the packages were renamed (apitoolkit-flask 1.0.3 on PyPI dates from 2024-12; monoscope-flask replaced it). Use the monoscope-* / @monoscopetech/* packages.

Access Roles¶

Project membership uses three permission levels (CLI: monoscope members add --permission view|edit|admin).

Permission	Meaning
`view`	Read dashboards, queries and issues
`edit`	Change dashboards, monitors and other project resources
`admin`	Manage members, API keys and project settings

The exact capability split per level is not documented beyond the names above (TBD, verify in the UI). Multi-tenant workspace support is still an open roadmap item.

Alert and Notification Channels¶

Channel	Self-hosted configuration
Email	SMTP (`SMTP_*`), SendGrid (`SENDGRIDAPIKEY`) or Postmark (`POSTMARK_TOKEN`)
Slack	Slack app OAuth (`SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_REDIRECT_URI`, bot token)
Discord	Discord app (`DISCORD_*`) or webhook URL
WhatsApp	Twilio (`TWILIO_`, `WHATSAPP_` templates)
PagerDuty and others	Listed as Cloud features in the README ("Slack, PagerDuty, etc."). Self-hosted setup is not documented (TBD)