Skip to content

docs(o11y-coroot): drop stale references to removed examples from ARCHITECTURE.md #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
intech merged 2 commits into from
Jul 6, 2026
Merged

docs(o11y-coroot): drop stale references to removed examples from ARCHITECTURE.md #39

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cdbe6ce
docs(o11y-coroot): drop stale references to removed examples from ARC…
intech Jul 5, 2026
e516fc8
docs(o11y-coroot): clarify that host port 8080 clashes across example…
intech Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions o11y-coroot/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ kernel tracing is not available: stat /sys/kernel/debug/tracing: no such file or
```

**Advantages**:
- Compatible with existing `production-ready` configuration (microservices already export to `otel-collector:4318`)
- The services' default OTLP endpoint (`otel-collector:4318`) works unchanged
- OTel Collector adds batch processing, resource attributes enrichment
- Single routing point — easy to add additional exporters
- Microservices DO NOT need to change `OTEL_EXPORTER_OTLP_ENDPOINT`
Expand Down Expand Up @@ -128,9 +128,9 @@ logs: [otlp] → [batch] → [otlphttp/coroot]
|-----------|-------|-------------|-----------|
| Coroot | `ghcr.io/coroot/coroot` | latest | Community Edition, frequently updated |
| ClickHouse | `clickhouse/clickhouse-server` | `24.3` | LTS, verified in official Coroot docker-compose |
| OTel Collector | `otel/opentelemetry-collector-contrib` | `0.115.0` | Matches production-ready for consistency |
| order-service | build context | local | From `production-ready/services/order-service` |
| inventory-service | build context | local | From `production-ready/services/inventory-service` |
| OTel Collector | `otel/opentelemetry-collector-contrib` | `0.120.0` | Current contrib release at the time of writing |
| order-service | build context | local | Built from the local `service/` directory |
| inventory-service | build context | local | Built from the local `service/` directory |

---

Expand All @@ -152,13 +152,12 @@ logs: [otlp] → [batch] → [otlphttp/coroot]

| Port | o11y-coroot | Conflict with | Resolution |
|------|-------------|---------------|------------|
| **8080** | Coroot UI | `with-events-redpanda` (Redpanda Console) | No conflict — separate docker networks, examples run independently |
| **5000-5001** | Microservices | `production-ready`, `runn` | No conflict — separate docker networks |
| **4317-4318** | OTel Collector | `production-ready`, `runn` | No conflict — separate docker networks |
| **8080** | Coroot UI | `with-events-redpanda` (Redpanda Console) | Both map **host** port 8080, so the stacks clash if started together — run one example at a time, or remap one side (e.g., `8081:8080`) |
| **5000-5001** | Microservices | — | Unique among the Docker-based examples |
| **4317-4318** | OTel Collector | — | Unique among the Docker-based examples |
| **9000** | ClickHouse | — | Unique among examples |
Comment thread
coderabbitai[bot] marked this conversation as resolved.
| **3000** | — | `production-ready` (Grafana) | NOT used in o11y-coroot |

**Conclusion**: No conflicts. All examples use isolated docker networks and are not run simultaneously. If simultaneous execution is needed, port mapping can be shifted (e.g., `8081:8080` for Coroot).
**Conclusion**: No conflicts when examples are run one at a time (the intended mode). Isolated docker networks separate container traffic, but they do NOT prevent **host** port collisions — for simultaneous runs, shift the clashing mapping (e.g., `8081:8080` for Coroot).

---

Expand Down Expand Up @@ -234,7 +233,7 @@ Host ports exposed:
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Metrics backend | ClickHouse (not Prometheus) | Coroot prioritizes CH; single backend for all telemetry |
| OTLP routing | Via OTel Collector | Compatible with production-ready, batch processing, extensibility |
| OTLP routing | Via OTel Collector | Keeps the services' default OTLP endpoint; batch processing, extensibility |
| Node agent | Excluded | Docker Desktop incompatibility, OTLP is sufficient |
| Cluster agent | Excluded | Kubernetes-only |
| Coroot UI port | 8080 | Coroot default, no conflicts |
Expand All @@ -249,16 +248,17 @@ Host ports exposed:
examples/o11y-coroot/
├── docker-compose.yml # All services: Coroot + CH + OTel + microservices
├── otel-collector-config.yaml # OTel Collector → Coroot routing
├── clickhouse/
│ └── config.xml # ClickHouse optimizations (log disabling)
├── services/
│ ├── order-service/ # Symlink or copy from production-ready
│ └── inventory-service/ # Symlink or copy from production-ready
└── README.md # Documentation (technical-writer)
├── clickhouse-users.xml # ClickHouse user configuration
├── prometheus.yml # Prometheus scrape configuration
├── service/ # Shared source for both microservices
│ ├── Dockerfile # Built twice: order-service and inventory-service
│ ├── proto/ src/ # Contracts and implementation
│ └── buf.gen.yaml buf.yaml # Proto codegen
├── scripts/
│ └── generate-traffic.sh # Demo traffic generator
└── README.md # Documentation
```

**Alternative to symlinks**: use `build.context: ../production-ready/services/order-service` to reference existing Dockerfiles directly without duplication.

---

## References
Expand Down