Setup Overview
This guide walks you through installing BizFirst Observe from zero: standing up Loki, Prometheus, Tempo, and Grafana; configuring BizFirstGO 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 BizFirstGO services on ports 4317/4318 and routes signals to Loki, Prometheus, and Tempo.
Loki
Log aggregation. Stores structured logs from all BizFirstGO 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 BizFirstGO dashboards, Explore, and alerting.
BizFirstGO 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 BizFirstGO services
Set 3 environment variables on each BizFirstGO 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 BizFirstGO 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 BizFirstGO 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 |
| BizFirstGO 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.