# jinkoso/jinko-observability architecture

> Architecture diagram of the GitHub repository jinkoso/jinko-observability, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jinkoso/jinko-observability
- Repository: https://github.com/jinkoso/jinko-observability

## Overview

jinko-observability is a shared Go library that standardizes logging, trace context, identity baggage, HTTP instrumentation, and async-job trace continuity for Jinko services. Its principal workflow configures OpenTelemetry, instruments inbound requests, carries identity and trace context through internal HTTP calls, and correlates logs with active spans; outbound third-party calls retain tracing but strip baggage. Async jobs use a separate inject/enqueue/extract flow. The README documents these capabilities; some subsystem internals were not sampled, so their paths and wiring are limited to evidence in the tree and documentation.

Main entry points: [`pkg/telemetry/telemetry.go`](https://github.com/jinkoso/jinko-observability/blob/main/pkg/telemetry/telemetry.go) (Telemetry setup), [`pkg/logger/logger.go`](https://github.com/jinkoso/jinko-observability/blob/main/pkg/logger/logger.go) (Logger), [`pkg/jobs/jobs.go`](https://github.com/jinkoso/jinko-observability/blob/main/pkg/jobs/jobs.go) (Job propagation), [`pkg/telemetry/baggage.go`](https://github.com/jinkoso/jinko-observability/blob/main/pkg/telemetry/baggage.go) (Identity baggage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Shared conventions"]
  node_conventions["Conventions"]
  node_baggage_keys["Baggage keys<br/>[baggage.go]"]
  node_environment_rules["Environment rules<br/>[environment.go]"]
end

subgraph group_telemetry["Trace context"]
  node_telemetry_init["Telemetry setup<br/>[telemetry.go]"]
  node_identity_baggage["Identity baggage<br/>[baggage.go]"]
  node_span_attributes["Baggage span copy<br/>[telemetry.go]"]
end

subgraph group_http["HTTP instrumentation"]
  node_http_server["Gin middleware<br/>[server.go]"]
  node_traced_client["Traced client<br/>[client.go]"]
  node_external_client["External client<br/>[client.go]"]
end

subgraph group_logging_jobs["Logs and jobs"]
  node_logger_api["Logger<br/>[logger.go]"]
  node_zap_logger["Zap backend<br/>[zap.go]"]
  node_trace_log_fields["Trace log fields<br/>[trace.go]"]
  node_job_helpers["Job propagation<br/>[jobs.go]"]
end

node_service(("Go service"))
node_otlp(("OTLP collector"))
node_internal_service(("Internal service"))
node_third_party(("Third-party API"))
node_job_queue["Async job queue"]
node_worker(("Job worker"))

node_service -->|"initializes"| node_telemetry_init
node_telemetry_init -->|"validates"| node_environment_rules
node_telemetry_init -->|"configures"| node_span_attributes
node_telemetry_init -->|"exports traces"| node_otlp
node_service -->|"installs middleware"| node_http_server
node_http_server -->|"provides request context"| node_service
node_service -->|"sets identity"| node_identity_baggage
node_identity_baggage -->|"uses keys"| node_baggage_keys
node_span_attributes -->|"promotes prefixes"| node_baggage_keys
node_service -->|"makes internal calls"| node_traced_client
node_traced_client -->|"propagates trace and baggage"| node_internal_service
node_service -->|"makes vendor calls"| node_external_client
node_external_client -->|"sends trace; strips baggage"| node_third_party
node_service -->|"emits logs"| node_logger_api
node_logger_api -->|"adds span IDs"| node_trace_log_fields
node_logger_api -->|"writes structured logs"| node_zap_logger
node_service -->|"injects trace carrier"| node_job_helpers
node_job_helpers -->|"returns carrier"| node_service
node_service -->|"enqueues carrier"| node_job_queue
node_job_queue -->|"delivers job"| node_worker
node_worker -->|"extracts carrier"| node_job_helpers

click node_conventions "https://github.com/jinkoso/jinko-observability/tree/main/pkg/conventions"
click node_baggage_keys "https://github.com/jinkoso/jinko-observability/blob/main/pkg/conventions/baggage.go"
click node_environment_rules "https://github.com/jinkoso/jinko-observability/blob/main/pkg/conventions/environment.go"
click node_telemetry_init "https://github.com/jinkoso/jinko-observability/blob/main/pkg/telemetry/telemetry.go"
click node_identity_baggage "https://github.com/jinkoso/jinko-observability/blob/main/pkg/telemetry/baggage.go"
click node_span_attributes "https://github.com/jinkoso/jinko-observability/blob/main/pkg/telemetry/telemetry.go"
click node_http_server "https://github.com/jinkoso/jinko-observability/blob/main/pkg/httpx/server.go"
click node_traced_client "https://github.com/jinkoso/jinko-observability/blob/main/pkg/httpx/client.go"
click node_external_client "https://github.com/jinkoso/jinko-observability/blob/main/pkg/httpx/client.go"
click node_logger_api "https://github.com/jinkoso/jinko-observability/blob/main/pkg/logger/logger.go"
click node_zap_logger "https://github.com/jinkoso/jinko-observability/blob/main/pkg/logger/zap.go"
click node_trace_log_fields "https://github.com/jinkoso/jinko-observability/blob/main/pkg/logger/trace.go"
click node_job_helpers "https://github.com/jinkoso/jinko-observability/blob/main/pkg/jobs/jobs.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_conventions,node_baggage_keys,node_environment_rules toneBlue
class node_telemetry_init,node_identity_baggage,node_span_attributes toneAmber
class node_http_server,node_traced_client,node_external_client,node_third_party toneMint
class node_logger_api,node_zap_logger,node_trace_log_fields,node_job_helpers,node_job_queue,node_worker toneRose
class node_service,node_otlp,node_internal_service toneIndigo
```

## Components

### Shared conventions

- [Conventions](https://github.com/jinkoso/jinko-observability/tree/main/pkg/conventions): `pkg/conventions`
- [Baggage keys](https://github.com/jinkoso/jinko-observability/blob/main/pkg/conventions/baggage.go): `pkg/conventions/baggage.go`
- [Environment rules](https://github.com/jinkoso/jinko-observability/blob/main/pkg/conventions/environment.go): `pkg/conventions/environment.go`

### Trace context

- [Telemetry setup](https://github.com/jinkoso/jinko-observability/blob/main/pkg/telemetry/telemetry.go): `pkg/telemetry/telemetry.go`
- [Identity baggage](https://github.com/jinkoso/jinko-observability/blob/main/pkg/telemetry/baggage.go): `pkg/telemetry/baggage.go`
- [Baggage span copy](https://github.com/jinkoso/jinko-observability/blob/main/pkg/telemetry/telemetry.go): `pkg/telemetry/telemetry.go`

### HTTP instrumentation

- [Gin middleware](https://github.com/jinkoso/jinko-observability/blob/main/pkg/httpx/server.go): `pkg/httpx/server.go`
- [Traced client](https://github.com/jinkoso/jinko-observability/blob/main/pkg/httpx/client.go): `pkg/httpx/client.go`
- [External client](https://github.com/jinkoso/jinko-observability/blob/main/pkg/httpx/client.go): `pkg/httpx/client.go`

### Logs and jobs

- [Logger](https://github.com/jinkoso/jinko-observability/blob/main/pkg/logger/logger.go): `pkg/logger/logger.go`
- [Zap backend](https://github.com/jinkoso/jinko-observability/blob/main/pkg/logger/zap.go): `pkg/logger/zap.go`
- [Trace log fields](https://github.com/jinkoso/jinko-observability/blob/main/pkg/logger/trace.go): `pkg/logger/trace.go`
- [Job propagation](https://github.com/jinkoso/jinko-observability/blob/main/pkg/jobs/jobs.go): `pkg/jobs/jobs.go`

### Other components

- **Go service**
- **OTLP collector**
- **Internal service**
- **Third-party API**
- **Async job queue**
- **Job worker**

## Connections

- Go service → Telemetry setup: initializes
- Telemetry setup → Environment rules: validates
- Telemetry setup → Baggage span copy: configures
- Telemetry setup → OTLP collector: exports traces
- Go service → Gin middleware: installs middleware
- Gin middleware → Go service: provides request context
- Go service → Identity baggage: sets identity
- Identity baggage → Baggage keys: uses keys
- Baggage span copy → Baggage keys: promotes prefixes
- Go service → Traced client: makes internal calls
- Traced client → Internal service: propagates trace and baggage
- Go service → External client: makes vendor calls
- External client → Third-party API: sends trace; strips baggage
- Go service → Logger: emits logs
- Logger → Trace log fields: adds span IDs
- Logger → Zap backend: writes structured logs
- Go service → Job propagation: injects trace carrier
- Job propagation → Go service: returns carrier
- Go service → Async job queue: enqueues carrier
- Async job queue → Job worker: delivers job
- Job worker → Job propagation: extracts carrier