Setup Overview
This guide walks you through installing BizFirst Observe from zero: standing up Loki, Prometheus, Tempo, and Grafana; configuring BizFirst services to send telemetry; and validating that logs, metrics, and traces are flowing end-to-end before your first production deployment.
What You Will Set Up
OTel Collector
Central telemetry fan-out. Receives OTLP from all BizFirst services on ports 4317/4318 and routes signals to Loki, Prometheus, and Tempo.
Loki
Log aggregation. Stores structured logs from all BizFirst services. Queried via LogQL in Grafana Explore and the Logs panels.
Prometheus
Metrics scraping and storage. Pulls /metrics endpoints from all services on a 15-second interval. Queried via PromQL.
Tempo
Distributed tracing. Receives trace spans via OTLP. Stores traces with S3-compatible object storage. Queried via TraceQL.
Grafana
Unified observability UI. Connects to all three backends. Hosts pre-built BizFirst dashboards, Explore, and alerting.
BizFirst Services
ProcessEngine, EdgeStream, Octopus — configured with 3 environment variables to send telemetry to the OTel Collector.
Setup Sequence
Verify prerequisites
Docker 24+ or Kubernetes 1.28+, 4 CPU / 16 GB RAM minimum, ports 3000/4317/4318/3100/9090/3200 available. Prerequisites page
Start the observability stack
docker compose up -d starts all components. Grafana available at http://localhost:3000 within ~30 seconds. Install the Stack
Configure BizFirst services
Set 3 environment variables on each BizFirst service: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES. Configure Services
Verify telemetry is flowing
Start one workflow execution. Check for logs in Loki, trace in Tempo, scrape target in Prometheus. Verify Ingestion
Import pre-built dashboards
Import the 10 BizFirst dashboard JSON files into Grafana. Set $tenant and $environment variables. Import Dashboards
Configure at least one alert contact point
Add a Slack webhook or email contact point. Import the BizFirst alert rules. Test fire an alert. Configure Alerts
Run the validation checklist
10 end-to-end validation checks to confirm the stack is production-ready. Validation Checklist
Estimated Setup Time
| Phase | Time | Notes |
|---|---|---|
| Stack startup (Docker Compose) | 15 minutes | Includes image pull time on first run |
| BizFirst service configuration | 30 minutes | Per service; env vars + restart |
| Ingestion verification | 15 minutes | Run one execution, check 3 signals |
| Dashboard import | 20 minutes | 10 JSON files + variable configuration |
| Alert configuration | 20 minutes | Contact point + import alert rules |
| Validation checklist | 15 minutes | 10 checks |
| Total | ~2 hours | For a single engineer from scratch |
Read Guide1_PhysicalArchitecture and Guide2_DefaultArchitecture before this setup guide. Understanding the architecture helps you troubleshoot when signals are not flowing as expected.