Nik Afiq 657b6aeb22 feat: implement initial application structure with health and hello endpoints

- Add bootstrap package to initialize application components including logger, tracer, and HTTP server.
- Create config package to load runtime settings from environment variables.
- Implement observability features including logging, metrics, and tracing.
- Add health check and hello use cases with corresponding HTTP handlers.
- Introduce middleware for request ID, access logging, metrics, and recovery.
- Set up HTTP router with defined routes for health and hello endpoints.
- Include tests for health and hello endpoints to ensure proper functionality.
- Add OpenTelemetry collector configuration for trace exporting.

2026-03-05 21:22:43 +09:00

1.9 KiB

Raw Permalink Blame History

switchbot-api service

Gin-based Go service with clean-ish layering, OpenTelemetry tracing (OTLP gRPC), Prometheus metrics, structured JSON logging, and graceful shutdown.

Project structure

cmd/server/main.go
internal/app/bootstrap
internal/app/config
internal/app/observability
internal/domain/hello
internal/domain/health
internal/transport/http

Endpoints

GET /healthz -> 200 {"status":"ok"}
GET /readyz -> 200 {"status":"ok"}
GET /hello -> 200 {"message":"hello world"}
GET /metrics -> Prometheus metrics

Configuration (environment variables)

PORT (default: 8080)
SERVICE_NAME (default: switchbot-api)
ENV (default: local)
LOG_LEVEL (default: info)
OTEL_EXPORTER_OTLP_ENDPOINT (default: empty; tracing export disabled)

OTEL example env vars

export SERVICE_NAME=switchbot-api
export ENV=local
export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317

Run locally (without collector)

Tracing export is disabled by default when OTEL_EXPORTER_OTLP_ENDPOINT is not set.

go mod tidy
go run ./cmd/server

Run with OpenTelemetry Collector (Docker Compose)

docker compose up --build

The collector prints received spans to stdout via the logging exporter.

Example requests

curl -i http://localhost:8080/healthz
curl -i http://localhost:8080/readyz
curl -i http://localhost:8080/hello
curl -s http://localhost:8080/metrics | head

Notes

Request ID is propagated using X-Request-Id (generated if missing).
Request logs include request_id, trace_id, and span_id.
Error responses include trace_id and request_id when available.
/readyz already has a usecase and checker abstraction with a TODO for future dependency checks.
Optional tracing backend (Jaeger/Tempo) is not required for this setup.

Verify

go test ./...
go vet ./...

1.9 KiB Raw Permalink Blame History