runtimes/js: add support for custom metrics (#2128)

Adds support for creating custom metrics in typescript apps. Depends on
#2109

Inspired by the implementation in the go runtime.
Metrics needs to be defined within a service, and will automatically add
the service label.

This implementation is backed by a SharedArrayBuffer, where each u64
slot is a metric value, created from js by the main thread. From js we
do atomic operation to update values on this buffer, and from rust we do
atomic load when collecting the metrics. The rust runtime is use to
coordinate what slot should be used for a label set, so that we can
support multiple workers updating the same metric.

---------

Co-authored-by: André Eriksson <[email protected]>

Author: fredr

Cargo.lock

@@ -0,0 +1,121 @@
+---
+seotitle: Custom metrics in Go
+seodesc: Learn how to define and use custom metrics in your Go backend application with Encore.
+title: Metrics
+subtitle: Track custom metrics in your Go application
+infobox: {
+  title: "Metrics",
+  import: "encore.dev/metrics",
+}
+lang: go
+---
+
+Encore provides built-in support for defining custom metrics in your Go applications. Once defined, metrics are automatically collected and displayed in the Encore Cloud Dashboard, and can be exported to third-party observability services.
+
+See the [Platform metrics documentation](/docs/platform/observability/metrics) for information about integrations with third-party services like Grafana Cloud and Datadog.
+
+## Defining custom metrics
+
+Define custom metrics by importing the [`encore.dev/metrics`](https://pkg.go.dev/encore.dev/metrics) package and
+creating a new metric using one of the `metrics.NewCounter` or `metrics.NewGauge` functions.
+
+For example, to count the number of orders processed:
+
+```go
+import "encore.dev/metrics"
+
+var OrdersProcessed = metrics.NewCounter[uint64]("orders_processed", metrics.CounterConfig{})
+
+func process(order *Order) {
+    // ...
+    OrdersProcessed.Increment()
+}
+```
+
+## Metric types
+
+Encore currently supports two metric types: counters and gauges.
+
+**Counters** measure the count of something. A counter's value must always increase, never decrease. (Note that the value gets reset to 0 when the application restarts.) Typical use cases include counting the number of requests, the amount of data processed, and so on.
+
+**Gauges** measure the current value of something. Unlike counters, a gauge's value can fluctuate up and down. Typical use cases include measuring CPU usage, the number of active instances running of a process, and so on.
+
+For information about their respective APIs, see the API documentation for [Counter](https://pkg.go.dev/encore.dev/metrics#Counter) and [Gauge](https://pkg.go.dev/encore.dev/metrics#Gauge).
+
+### Counter example
+
+```go
+import "encore.dev/metrics"
+
+var RequestsReceived = metrics.NewCounter[uint64]("requests_received", metrics.CounterConfig{})
+
+func handleRequest() {
+    RequestsReceived.Increment()
+    // ... handle request
+}
+```
+
+### Gauge example
+
+```go
+import "encore.dev/metrics"
+
+var ActiveConnections = metrics.NewGauge[int64]("active_connections", metrics.GaugeConfig{})
+
+func onConnect() {
+    ActiveConnections.Add(1)
+}
+
+func onDisconnect() {
+    ActiveConnections.Add(-1)
+}
+```
+
+## Defining labels
+
+Encore's metrics package provides a type-safe way of attaching labels to metrics. To define labels, create a struct type representing the labels and then use `metrics.NewCounterGroup` or `metrics.NewGaugeGroup`.
+
+The Labels type must be a named struct, where each field corresponds to a single label. Each field must be of type `string`, `int`, or `bool`.
+
+### Counter with labels
+
+```go
+import "encore.dev/metrics"
+
+type Labels struct {
+    Success bool
+}
+
+var OrdersProcessed = metrics.NewCounterGroup[Labels, uint64]("orders_processed", metrics.CounterConfig{})
+
+func process(order *Order) {
+    var success bool
+    // ... populate success with true/false ...
+    OrdersProcessed.With(Labels{Success: success}).Increment()
+}
+```
+
+### Gauge with labels
+
+```go
+import "encore.dev/metrics"
+
+type ConnectionLabels struct {
+    Region string
+}
+
+var ActiveConnections = metrics.NewGaugeGroup[ConnectionLabels, int64]("active_connections", metrics.GaugeConfig{})
+
+func onConnect(region string) {
+    ActiveConnections.With(ConnectionLabels{Region: region}).Add(1)
+}
+```
+
+<Callout type="important">
+
+Each combination of label values creates a unique time series tracked in memory and stored by the monitoring system.
+Using numerous labels can lead to a combinatorial explosion, causing high cloud expenses and degraded performance.
+
+As a general rule, limit the unique time series to tens or hundreds at most, rather than thousands.
+
+</Callout>

docs/go/observability/metrics.md

@@ -455,6 +455,11 @@
 				text: "Logging"
 				path: "/go/observability/logging"
 				file: "go/observability/logging"
+			}, {
+				kind: "basic"
+				text: "Metrics"
+				path: "/go/observability/metrics"
+				file: "go/observability/metrics"
 			}]
 		},
 		{
@@ -948,6 +953,11 @@
 				text: "Service Catalog"
 				path: "/ts/observability/service-catalog"
 				file: "ts/observability/service-catalog"
+			}, {
+				kind: "basic"
+				text: "Metrics"
+				path: "/ts/observability/metrics"
+				file: "ts/observability/metrics"
 			}]
 		},
 		{

docs/menu.cue

@@ -24,64 +24,11 @@ By default, Encore also exports metrics data to your cloud provider's built-in m
 
 ## Defining custom metrics
 
-Define custom metrics by importing the [`encore.dev/metrics`](https://pkg.go.dev/encore.dev/metrics) package and
-create a new metric using one of the `metrics.NewCounter` or `metrics.NewGauge` functions.
+Encore makes it easy to define custom metrics for your application. Once defined, custom metrics are automatically displayed on the metrics page in the Cloud Dashboard.
 
-For example, to count the number of orders processed:
-
-```go
-import "encore.dev/metrics"
-
-var OrdersProcessed = metrics.NewCounter[uint64]("orders_processed", metrics.CounterConfig{})
-
-func process(order *Order) {
-    // ...
-    OrdersProcessed.Increment()
-}
-```
-
-### Metric types
-
-Encore currently supports two metric types: counters and gauges.
-
-Counters, like the name suggests, measure the count of something. A counter's value must always
-increase, never decrease. (Note that the value gets reset to 0 when the application restarts.)
-Typical use cases include counting the number of requests, the amount of data processed, and so on.
-
-Gauges measure the current value of something. Unlike counters, a gauge's value can fluctuate up and down. Typical use
-cases include measuring CPU usage, the number of active instances running of a process, and so on.
-
-For information about their respective APIs, see the API documentation
-for [Counter](https://pkg.go.dev/encore.dev/metrics#Counter) and [Gauge](https://pkg.go.dev/encore.dev/metrics#Gauge).
-
-### Defining labels
-
-Encore's metrics package provides a type-safe way of attaching labels to metrics.
-To define labels, create a struct type representing the labels and then use `metrics.NewCounterGroup`
-or `metrics.NewGaugeGroup`:
-
-```go
-type Labels struct {
-    Success bool
-}
-
-var OrdersProcessed = metrics.NewCounterGroup[Labels, uint64]("orders_processed", metrics.CounterConfig{})
-
-func process(order *Order) {
-    var success bool
-    // ... populate success with true/false ...
-    OrdersProcessed.With(Labels{Success: success}).Increment()
-}
-```
-
-<Callout type="important">
-
-Each combination of label values creates a unique time series tracked in memory and stored by the monitoring system.
-Using numerous labels can lead to a combinatorial explosion, causing high cloud expenses and degraded performance.
-
-As a general rule, limit the unique time series to tens or hundreds at most, rather than thousands.
-
-</Callout>
+For implementation guides on how to define metrics in your code, see:
+- [Go metrics documentation](/docs/go/observability/metrics)
+- [TypeScript metrics documentation](/docs/ts/observability/metrics)
 
 ## Integrations with third party observability services