<a id="integrations"></a>

# Integrations

The Go framework extension gives `gopkg-k8s` the endpoints below. To
connect the observability endpoints, follow [How to integrate with COS Lite](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/integrate-with-cos/index.html.md#integrate-with-cos); for
ingress, follow [How to configure ingress](https://canonical.com/juju/docs/gopkg-charm/latest/how-to/configure-ingress/index.html.md#configure-ingress). The `secret-storage` peer relation
is internal to the extension. For how the extension implements these
endpoints, see [Relations](https://canonical.com/juju/docs/charmcraft/4/reference/extensions/go-framework-extension/#go-framework-extension-relations) and
[Observability](https://canonical.com/juju/docs/charmcraft/4/reference/extensions/go-framework-extension/#go-framework-extension-observability).

| Endpoint            | Role     | Interface           | Carries                                                                                                                                                                                  |
|---------------------|----------|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ingress`           | requires | `ingress`           | The service’s address and port, so an ingress charm such as<br/>`nginx-ingress-integrator` routes external HTTP traffic to it.                                                           |
| `logging`           | requires | `loki_push_api`     | The Loki endpoint. Pebble forwards the service’s standard output,<br/>one JSON record per line, labelled with the Juju topology. The Loki<br/>alert rules travel over the same relation. |
| `metrics-endpoint`  | provides | `prometheus_scrape` | A scrape job for `metrics-path` on `metrics-port` of every unit,<br/>and the Prometheus alert rules.                                                                                     |
| `grafana-dashboard` | provides | `grafana_dashboard` | The **gopkg Overview** dashboard and the extension’s **Go Operator**<br/>dashboard.                                                                                                      |

## Observability options

`metrics-port` (default `8080`, the application port) and
`metrics-path` (default `/metrics`) are framework options that reach the
service as `APP_METRICS_PORT` and `APP_METRICS_PATH`. When the port
differs from the application port, the service opens a second listener that
serves only the metrics path, which keeps the endpoint off the port that
ingress publishes. The path must be absolute and must not be `/` or
`/health-check`. See [charmcraft.yaml > config > options](https://canonical.com/juju/docs/charmcraft/4/reference/extensions/go-framework-extension/#go-framework-extension-config-options)
for every framework option.

<a id="integrations-metrics"></a>

## Metrics

Besides the standard Go runtime and process collectors, the service exposes
the following metrics. Label values are bounded: routes are a fixed set of
names, the method is one of `GET`, `HEAD`, `POST` or `other`, and
import paths, repository names, client addresses, and error text are never
labels.

| Metric                                    | Labels                           | Meaning                                                     |
|-------------------------------------------|----------------------------------|-------------------------------------------------------------|
| `gopkg_http_requests_total`               | `method`, `route`, `status_code` | Requests handled, by route and response status.             |
| `gopkg_http_request_duration_seconds`     | `method`, `route`                | Request latency histogram.                                  |
| `gopkg_upstream_requests_total`           | `service`, `operation`, `result` | Calls to GitHub and godoc.org, by outcome.                  |
| `gopkg_upstream_request_duration_seconds` | `service`, `operation`           | Upstream call latency histogram.                            |
| `gopkg_refs_cache_requests_total`         | `result`                         | Repository refs cache hits and misses.                      |
| `gopkg_refs_cache_entries`                | none                             | Entries held in the in-memory refs cache.                   |
| `gopkg_refs_retries_total`                | none                             | GitHub refs requests retried after a timeout.               |
| `gopkg_git_upload_pack_bytes_total`       | `direction`                      | Bytes proxied for `git-upload-pack` requests and responses. |

The `route` label takes one of `health_check`, `root_redirect`,
`go_get`, `package_page`, `git_info_refs`, `git_upload_pack`, and
`not_found`.

<a id="integrations-logs"></a>

## Logs

The service writes one JSON record per line to standard output. Request
records carry `method`, `path`, `route`, `status_code`, and
`duration_ms`; health checks are not logged. Failures are recorded at
level `ERROR`, and a fatal start-up or server error is logged as
`application stopped` before the process exits.

<a id="integrations-alert-rules"></a>

## Alert rules

The charm ships these rules in `app/charm/cos_custom`. Prometheus and Loki
receive them through the integrations and evaluate them with the Juju
topology of the deployment.

- `GopkgTargetDown` (critical): a unit has not been scraped successfully
  for five minutes.
- `GopkgHighServerErrorRatio` (critical): more than 5% of requests return a
  5xx status for five minutes, under sustained traffic.
- `GopkgHighRequestLatency` (warning): the 95th percentile latency of the
  functional routes exceeds two seconds for ten minutes.
- `GopkgGitHubFailureRatio` (warning): more than 20% of GitHub operations
  fail for five minutes, under sustained traffic.
- `GopkgApplicationStopped` (critical, Loki): the process logged
  `application stopped`.
- `GopkgErrorLogSpike` (warning, Loki): more than ten `ERROR` records in
  five minutes.