foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-24 18:09:26 -05:00
Code Issues Activity
forgejo-docs/docs/admin/otel.md
TheFox0x7 202c7aa6a7 OpenTelemetry documentation (#739) 
Documentation for opentelemetry feature https://codeberg.org/forgejo/forgejo/pulls/3972

Reviewed-on: https://codeberg.org/forgejo/docs/pulls/739
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Co-authored-by: TheFox0x7 <thefox0x7@gmail.com>
Co-committed-by: TheFox0x7 <thefox0x7@gmail.com>
2024-08-05 06:05:35 +00:00

3 KiB
Raw Blame History

title license
Open Telemetry integration CC-BY-SA-4.0

OpenTelemetry is a open source standard which allows for instrumentation of an application. It enabled administrator to measure Forgejo performance to find potential issues and act on them before they become unmanagable or just for debugging performance.

Forgejo currently implements only tracing part of the specification, with metrics handled by Prometheus.

Quick Setup

Administrator can enable the feature by setting the feature flag [opentelemetry].ENABLED to true. The predefined exporter configuration will try to send data to localhost:4318 via http/protobuf protocol.

Resources

Administrator can set the name and custom attributes to enrich the exported items with more metadata. By default Forgejo sets service.name to forgejo, but this can be changed with [opentelemetry].SERVICE_NAME setting. Custom resource attributes can be set with [opentelemetry].RESOURCE_ATTRIBUTES in format key=value,key2=value2. It's best to follow the Semantic Conventions for resource while adding custom attributes as collection stores may visualize them better or handle in a more specific way.

Additionally more metadata can be automatically added using resource detectors controllable with [opentelemetry].RESOURCE_DETECTORS. Available options can be found in config cheat sheet. The detectors aren't a stable Open Telemetry specification and can be removed or added later releases.

Tracing

Traces are one of signals in Open Telemetry specification. Gathering of them can be turned off and on individually by setting [opentelemetry].TRACES_EXPORTER=none to disable exporter and therefore traces. Alternatively it can be set to otlp, which is the default and only other supported value, to enable the OTLP exporter.

Which spans will be sent can be infuenced with [opentelemetry].TRACES_SAMPLER and [opentelemetry].TRACES_SAMPLER_ARG options. Not all samplers support the argument. More details can be found in the config cheat sheet.

OTLP Exporter

The default exporter is configurable in [opentelemetry.exporter.otlp] section and it's subsections if needed. It follows naming of the opentelemetry exporter configuration options all of which are listed below:

  • ENDPOINT=http://localhost:4318 - urlf for the collector
  • CERTIFICATE= - path to certificate for TLS
  • CLIENT_CERTIFICATE= - path to client certificate for TLS
  • CLIENT_KEY= - path to client key for TLS
  • COMPRESSION= - compression switch, can be set to gzip
  • HEADERS= - key value list of headers to use
  • PROTOCOL=http/protobuf - which protocol to use for exports, supports grpc and http/protobuf
  • TIMEOUT=10s - controls the timeout of the export

If ENDPOINT contains unix or http the insecure flag is transparently set.