From 06b31f545a14a4e0eae4cf3d191adee84fef0b89 Mon Sep 17 00:00:00 2001 From: Asim Aslam Date: Thu, 13 Nov 2025 18:59:34 +0000 Subject: [PATCH] update the docs to easily navigate --- internal/website/docs/architecture.md | 6 + .../adr-009-progressive-configuration.md | 1 + .../website/docs/architecture/adr-template.md | 37 +++++ internal/website/docs/config.md | 128 ++++++++++++++++++ internal/website/docs/contributing.md | 65 +++++++++ internal/website/docs/examples/index.md | 4 + internal/website/docs/index.md | 4 + internal/website/docs/observability.md | 93 +++++++++++++ internal/website/docs/roadmap.md | 35 +++++ 9 files changed, 373 insertions(+) create mode 100644 internal/website/docs/architecture/adr-template.md create mode 100644 internal/website/docs/config.md create mode 100644 internal/website/docs/contributing.md create mode 100644 internal/website/docs/observability.md create mode 100644 internal/website/docs/roadmap.md diff --git a/internal/website/docs/architecture.md b/internal/website/docs/architecture.md index da11cce5..c5547c56 100644 --- a/internal/website/docs/architecture.md +++ b/internal/website/docs/architecture.md @@ -45,6 +45,12 @@ in the plugins repo. State and persistence becomes a core requirement beyond pro We will share more on architecture soon +## Related + +- [ADR Index](architecture/index.md) +- [Configuration](config.md) +- [Plugins](plugins.md) + ## Example Usage Here's a minimal Go Micro service demonstrating the architecture: diff --git a/internal/website/docs/architecture/adr-009-progressive-configuration.md b/internal/website/docs/architecture/adr-009-progressive-configuration.md index c2fa0084..88a9a8ea 100644 --- a/internal/website/docs/architecture/adr-009-progressive-configuration.md +++ b/internal/website/docs/architecture/adr-009-progressive-configuration.md @@ -150,3 +150,4 @@ func (s *service) Init() error { - [ADR-004: mDNS as Default Registry](adr-004-mdns-default-registry.md) - ADR-008: Environment Variable Support (planned) - [Getting Started Guide](../getting-started.md) - Configuration examples + - [Configuration Guide](../config.md) diff --git a/internal/website/docs/architecture/adr-template.md b/internal/website/docs/architecture/adr-template.md new file mode 100644 index 00000000..3d231d04 --- /dev/null +++ b/internal/website/docs/architecture/adr-template.md @@ -0,0 +1,37 @@ +--- +layout: default +--- + +# ADR-XXX: Title + +Status: Proposed +Date: YYYY-MM-DD + +## Context + +Describe the problem, forces, and constraints leading to the decision. + +## Decision + +State the decision clearly and precisely. + +## Consequences + +Positive and negative outcomes, trade-offs introduced by this decision. + +## Alternatives Considered + +1. Alternative A - why rejected +2. Alternative B - why rejected + +## Implementation Notes + +High-level steps or rollout plan if accepted. + +## Related + +- Link other ADRs, documentation, or issues. + +## References + +External resources, prior art, research. diff --git a/internal/website/docs/config.md b/internal/website/docs/config.md new file mode 100644 index 00000000..d2d82327 --- /dev/null +++ b/internal/website/docs/config.md @@ -0,0 +1,128 @@ +--- +layout: default +--- + +# Configuration + +Go Micro follows a progressive configuration model so you can start with zero setup and layer in complexity only when needed. + +## Levels of Configuration + +1. Zero Config (Defaults) + - mDNS registry, HTTP transport, in-memory broker/store +2. Environment Variables + - Override core components without code changes +3. Code Options + - Fine-grained control via functional options +4. External Sources (Future / Plugins) + - Configuration loaded from files, vaults, or remote services + +## Core Environment Variables + +| Component | Variable | Example | Purpose | +|-----------|----------|---------|---------| +| Registry | `MICRO_REGISTRY` | `MICRO_REGISTRY=consul` | Select registry implementation | +| Registry Address | `MICRO_REGISTRY_ADDRESS` | `MICRO_REGISTRY_ADDRESS=127.0.0.1:8500` | Point to registry service | +| Broker | `MICRO_BROKER` | `MICRO_BROKER=nats` | Select broker implementation | +| Broker Address | `MICRO_BROKER_ADDRESS` | `MICRO_BROKER_ADDRESS=nats://localhost:4222` | Broker endpoint | +| Transport | `MICRO_TRANSPORT` | `MICRO_TRANSPORT=nats` | Select transport implementation | +| Transport Address | `MICRO_TRANSPORT_ADDRESS` | `MICRO_TRANSPORT_ADDRESS=nats://localhost:4222` | Transport endpoint | +| Store | `MICRO_STORE` | `MICRO_STORE=postgres` | Select store implementation | +| Store Database | `MICRO_STORE_DATABASE` | `MICRO_STORE_DATABASE=app` | Logical database name | +| Store Table | `MICRO_STORE_TABLE` | `MICRO_STORE_TABLE=records` | Default table/collection | +| Store Address | `MICRO_STORE_ADDRESS` | `MICRO_STORE_ADDRESS=postgres://user:pass@localhost:5432/app?sslmode=disable` | Connection string | +| Server Address | `MICRO_SERVER_ADDRESS` | `MICRO_SERVER_ADDRESS=:8080` | Bind address for RPC server | + +## Example: Switching Components via Env Vars + +```bash +# Use NATS for broker and transport, Consul for registry +export MICRO_BROKER=nats +export MICRO_TRANSPORT=nats +export MICRO_REGISTRY=consul +export MICRO_REGISTRY_ADDRESS=127.0.0.1:8500 + +# Run your service +go run main.go +``` + +No code changes required. The framework internally wires the selected implementations. + +## Equivalent Code Configuration + +```go +service := micro.NewService( + micro.Name("helloworld"), + micro.Broker(nats.NewBroker()), + micro.Transport(natstransport.NewTransport()), + micro.Registry(consul.NewRegistry(registry.Addrs("127.0.0.1:8500"))), +) +service.Init() +``` + +Use env vars for deployment level overrides; use code options for explicit control or when composing advanced setups. + +## Precedence Rules + +1. Explicit code options always win +2. If not set in code, env vars are applied +3. If neither code nor env vars set, defaults are used + +## Discoverability Strategy + +Defaults allow local development with zero friction. As teams scale: +- Introduce env vars for staging/production parity +- Consolidate secrets (e.g. store passwords) using external secret managers (future guide) +- Move to service mesh aware registry (Consul/NATS JetStream) + +## Validating Configuration + +Enable debug logging to confirm selected components: + +```bash +MICRO_LOG_LEVEL=debug go run main.go +``` + +You will see lines like: + +```text +Registry [consul] Initialised +Broker [nats] Connected +Transport [nats] Listening on nats://localhost:4222 +Store [postgres] Connected to app/records +``` + +## Patterns + +### Twelve-Factor Alignment +Environment variables map directly to deploy-time configuration. Avoid hardcoding component choices so services remain portable. + +### Multi-Environment Setup +Use a simple env file per environment: + +```bash +# .env.staging +MICRO_REGISTRY=consul +MICRO_REGISTRY_ADDRESS=consul.staging.internal:8500 +MICRO_BROKER=nats +MICRO_BROKER_ADDRESS=nats.staging.internal:4222 +MICRO_STORE=postgres +MICRO_STORE_ADDRESS=postgres://staging:pass@pg.staging.internal:5432/app?sslmode=disable +``` + +Load with your process manager or container orchestrator. + +## Troubleshooting + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Service starts with memory store unexpectedly | Env vars not exported | `env | grep MICRO_STORE` to verify | +| Consul errors about connection refused | Wrong address/port | Check `MICRO_REGISTRY_ADDRESS` value | +| NATS connection timeout | Server not running | Start NATS or change address | +| Postgres SSL errors | Missing sslmode param | Append `?sslmode=disable` locally | + +## Related + +- [ADR-009: Progressive Configuration](architecture/adr-009-progressive-configuration.md) +- [Getting Started](getting-started.md) +- [Plugins](plugins.md) diff --git a/internal/website/docs/contributing.md b/internal/website/docs/contributing.md new file mode 100644 index 00000000..353dfa2e --- /dev/null +++ b/internal/website/docs/contributing.md @@ -0,0 +1,65 @@ +--- +layout: default +--- + +# Contributing + +This is a rendered copy of the repository `CONTRIBUTING.md` for convenient access via the documentation site. + +## Overview + +Go Micro welcomes contributions of all kinds: code, documentation, examples, and plugins. + +## Quick Start + +```bash +git clone https://github.com/micro/go-micro.git +cd go-micro +go mod download +go test ./... +``` + +## Process + +1. Fork and create a feature branch +2. Make focused changes with tests +3. Run linting and full test suite +4. Open a PR describing motivation and approach + +## Commit Format + +Use conventional commits: + +``` +feat(registry): add consul health check +fix(broker): prevent reconnect storm +``` + +## Testing + +Run unit tests: +```bash +go test ./... +``` +Run race/coverage: +```bash +go test -race -coverprofile=coverage.out ./... +``` + +## Plugins + +Place new plugins under the appropriate interface directory (e.g. `registry/consul/`). Include tests and usage examples. Document env vars and options. + +## Documentation + +Docs live in `internal/website/docs/`. Add new examples under `internal/website/docs/examples/`. + +## Help & Questions + +Use GitHub Discussions or the issue templates. For general usage questions open a "Question" issue. + +## Full Guide + +For complete details see the repository copy of the guide on GitHub. + +- View on GitHub: https://github.com/micro/go-micro/blob/master/CONTRIBUTING.md diff --git a/internal/website/docs/examples/index.md b/internal/website/docs/examples/index.md index a3270be3..8aec43b6 100644 --- a/internal/website/docs/examples/index.md +++ b/internal/website/docs/examples/index.md @@ -12,3 +12,7 @@ A collection of small, focused examples demonstrating common patterns with Go Mi - [Service Discovery with Consul](registry-consul.md) - [State with Postgres Store](store-postgres.md) - [NATS Transport](transport-nats.md) + +## More + +- [Real-World Examples](realworld/index.md) diff --git a/internal/website/docs/index.md b/internal/website/docs/index.md index ddc33570..6f05d179 100644 --- a/internal/website/docs/index.md +++ b/internal/website/docs/index.md @@ -27,6 +27,7 @@ about the framework. - [Getting Started](getting-started.md) - [Architecture](architecture.md) +- [Configuration](config.md) - [Registry](registry.md) - [Broker](broker.md) - [Client/Server](client-server.md) @@ -42,3 +43,6 @@ about the framework. - [Architecture Decisions](architecture/index.md) - [Real-World Examples](examples/realworld/index.md) - [Migration Guides](guides/migration/index.md) +- [Observability](observability.md) +- [Contributing](contributing.md) +- [Roadmap](roadmap.md) diff --git a/internal/website/docs/observability.md b/internal/website/docs/observability.md new file mode 100644 index 00000000..8907fc79 --- /dev/null +++ b/internal/website/docs/observability.md @@ -0,0 +1,93 @@ +--- +layout: default +--- + +# Observability + +Observability in Go Micro spans logs, metrics, and traces. The goal is rapid insight into service behavior with minimal configuration. + +## Core Principles + +1. Structured Logs – Machine-parsable, leveled output +2. Metrics – Quantitative trends (counters, gauges, histograms) +3. Traces – Request flows across service boundaries +4. Correlation – IDs flowing through all three signals + +## Logging + +The default logger can be replaced. Use env vars to adjust level: + +```bash +MICRO_LOG_LEVEL=debug go run main.go +``` + +Recommended fields: +- `service` – service name +- `version` – release identifier +- `trace_id` – propagated context id +- `span_id` – current operation id + +## Metrics + +Patterns: +- Emit counters for request totals +- Use histograms for latency +- Track error rates per endpoint + +Example (pseudo-code): + +```go +// Wrap handler to record metrics +func MetricsWrapper(fn micro.HandlerFunc) micro.HandlerFunc { + return func(ctx context.Context, req micro.Request, rsp interface{}) error { + start := time.Now() + err := fn(ctx, req, rsp) + latency := time.Since(start) + metrics.Inc("requests_total", req.Endpoint(), errorLabel(err)) + metrics.Observe("request_latency_seconds", latency, req.Endpoint()) + return err + } +} +``` + +## Tracing + +Distributed tracing links calls across services. + +Propagation strategy: +- Extract trace context from incoming headers +- Inject into outgoing RPC calls/broker messages +- Create spans per handler and client call + +## Local Development Strategy + +Start with only structured logs. Add metrics when operating multiple services. Introduce tracing once debugging multi-hop latency or failures. + +## Roadmap (Planned Enhancements) + +- Native OpenTelemetry exporter helpers +- Automatic handler/client wrapping for spans +- Default correlation IDs across broker messages + +## Deployment Recommendations + +| Scale | Suggested Stack | +|-------|-----------------| +| Dev | Console logs only | +| Staging | Logs + basic metrics (Prometheus) | +| Prod (basic) | Logs + metrics + sampling traces | +| Prod (complex) | Full tracing + profiling + anomaly detection | + +## Troubleshooting + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Missing trace IDs in logs | Context not propagated | Ensure wrappers add IDs | +| Metrics server empty | Endpoint not scraped | Verify Prometheus config | +| High cardinality metrics | Dynamic labels | Reduce labeled dimensions | + +## Related + +- [Getting Started](getting-started.md) +- [Plugins](plugins.md) +- [Architecture Decisions](architecture/index.md) diff --git a/internal/website/docs/roadmap.md b/internal/website/docs/roadmap.md new file mode 100644 index 00000000..687d4e07 --- /dev/null +++ b/internal/website/docs/roadmap.md @@ -0,0 +1,35 @@ +--- +layout: default +--- + +# Roadmap + +This page mirrors the repository `ROADMAP.md` for easy browsing. + +## Focus Areas (Q1 2026) +- Documentation expansion +- Observability integration (OpenTelemetry planned) +- Developer tooling improvements + +## Highlights + +See the full roadmap on GitHub for detailed quarterly goals: + +- Production readiness (graceful shutdown, health checks) +- Cloud native deployment patterns (operator, Helm charts) +- Security enhancements (mTLS, secrets integration) +- Plugin ecosystem growth + +## Contributing to the Roadmap + +Pick an item, open an issue, propose an approach, then submit a PR. + +High priority: documentation, examples, performance improvements, plugin development. + +## Full Document + +View the complete roadmap including long-term vision and version support: + +- GitHub: https://github.com/micro/go-micro/blob/master/ROADMAP.md + +_Last synced: November 2025_