Documentation updates for the upcoming v1.0 launch (#49)

laulauland · Gerry Agbobada · web-flow · commit 162bf08b2619 · 2023-12-04T13:45:50.000+01:00
* move k8s up

* update golang to include otel instructions

* update python to include otel instructions

* tweak rust things

* Update Golang documentation for 1.0 release

---------

Co-authored-by: Gerry Agbobada &lt;gerry@fiberplane.com&gt;
diff --git a/src/pages/deploying-prometheus/_meta.json b/src/pages/deploying-prometheus/_meta.json
@@ -1,11 +1,8 @@
 {
-  "docker": "Docker",
-  "local": "Local",
-  "kubernetes": "Kubernetes",
-	
-  "fly-io": "Fly.io",
-  "northflank": "Northflank",
-  "railway": "Railway"
-
-  
+	"docker": "Docker",
+	"kubernetes": "Kubernetes",
+	"local": "Local",
+	"fly-io": "Fly.io",
+	"northflank": "Northflank",
+	"railway": "Railway"
 }
diff --git a/src/pages/go/adding-version-information.mdx b/src/pages/go/adding-version-information.mdx
@@ -9,27 +9,25 @@ It produces a `build_info` metric and uses labels to expose the version, commit
 Example:
 
 ```prometheus 
-build_info{branch="main",commit="5cc2aa5447907fbf0a7ddd",version="1.0.0"} 1
+build_info{branch="main",commit="5cc2aa5447907fbf0a7ddd",version="1.0.0",service_name="Billing",repository_url="",repository_provider=""} 1
 ```
 
 ## Usage
 
-To add version information to your metrics, simply fill the `autometrics.BuildInfo` parameter to the `autometrics.Init()` call:
+To add version information to your metrics, simply add the relevant option parameters to the `autometrics.Init()` call:
 
 ```go {4-8} filename="main.go"
 autometrics.Init(
-    nil,
-    autometrics.DefBuckets,
-    autometrics.BuildInfo{
-        Version: "<version_here>",
-        Commit:  "<git_commit_hash_here",
-        Branch:  "<git_branch_here>",
-    },
-    nil,
+    autometrics.WithService("<service_name_here>"),
+    autometrics.WithVersion("<version_here>"),
+    autometrics.WithCommit("<git_commit_hash_here>"),
+    autometrics.WithBranch("<git_branch_here>"),
 )
 ```
 
-`autometrics.BuildInfo` parameter accepts each fields as strings which you can set as you wish or use something like `ldflags` to set them at build time.
+All `With...` initialization settings are optional, and not setting them will leave the label empty like `repository_url` and `repository_provider` in the example above.
+
+`autometrics.With...` options accept most fields as strings which you can set as you wish or use something like `ldflags` to set them at build time. Check the documentation on pkg.go.dev (for [Prometheus version](https://pkg.go.dev/github.com/autometrics-dev/autometrics-go/prometheus/autometrics) or [Open Telemetry version](https://pkg.go.dev/github.com/autometrics-dev/autometrics-go/otel/autometrics)) for more details about the initialization settings (all functions returning `autometrics.Option`).
 
 ## Using `ldflags` to add version information at build time
 
@@ -49,14 +47,10 @@ var (
 
 ```go {4-8} filename="main.go"
 autometrics.Init(
-    nil,
-    autometrics.DefBuckets,
-    autometrics.BuildInfo{
-        Version: Version,
-        Commit:  Commit,
-        Branch:  Branch,
-    },
-    nil,
+    autometrics.WithService("Billing"),
+    autometrics.WithVersion(Version),
+    autometrics.WithCommit(Commit),
+    autometrics.WithBranch(Branch),
 )
 ```
 
diff --git a/src/pages/go/quickstart.mdx b/src/pages/go/quickstart.mdx
@@ -13,21 +13,25 @@ There is a one-time setup phase to prime the code for autometrics. Once this pha
 
 The generator is the binary in cmd/autometrics, so the easiest way to get it is to install it through Go:
 
-```bash
+```bash filename="Shell"
 go install github.com/autometrics-dev/autometrics-go/cmd/autometrics@latest
 ```
 
 ### Add the generator to your PATH
 
-In order to have autometrics visible then, make sure that the directory $GOBIN (or the default $GOPATH/bin) is in your $PATH:
+In order to have autometrics visible then, make sure that the directory `$GOBIN` (or the default `$GOPATH/bin`) is in your `$PATH`:
 
-```bash
+```bash filename="Shell"
 echo "$PATH" | grep -q "${GOBIN:-$GOPATH/bin}" && echo "GOBIN in PATH" || echo "GOBIN not in PATH, please add it"
 GOBIN in PATH
 ```
 
 ## Instructions
 
+<Tabs items={["Using Prometheus client","Using OpenTelemetry"]}>
+
+<Tab>
+
 <Steps>
 
 ### Import the library in your code
@@ -43,16 +47,25 @@ import (
 And then in your main function initialize the metrics:
 
 ```go filename="main.go"
-	autometrics.Init(
-		nil,
-		autometrics.DefBuckets,
-		autometrics.BuildInfo{},
-                nil,
-	)
+	autometrics.Init()
 ```
 
 ### Add `go:generate autometrics` to your code
 
+#### Automatically
+
+You can use the `am` binary and its `instrument` subcommand to automatically instrument your whole codebase. You can also use a grep invocation:
+
+```bash filename="Shell"
+# On Linux, use sed, not gsed
+find . \
+  -type d -name vendor -prune -or \
+  -type f -name '*.go' \
+  -print0 | xargs -0 gsed -i -e '/package/{a\//go:generate autometrics --inst-all --no-doc' -e ':a;n;ba}'
+```
+
+#### Manually
+
 The manual changes you need to do are:
 
 ```go filename="main.go"
@@ -71,13 +84,7 @@ If you want the generated metrics to contain the function success rate, you must
 
 ### Generate the documentation and instrumentation code
 
-Install the go generator using `go install` as usual:
-
-```bash filename="Shell"
-go install https://github.com/autometrics-dev/autometrics-go/cmd/autometrics@latest
-```
-
-Once you've done this, the `autometrics` generator takes care of the rest, and you can
+As you have installed the generator as part of the prerequisites, it will take care of the rest, and you can
 simply call `go generate` with an optional environment variable:
 
 ```bash filename="Shell"
@@ -107,10 +114,10 @@ import (
 
 func main() {
 	autometrics.Init(
-		"web-server",
-		autometrics.DefBuckets,
-		autometrics.BuildInfo{},
-                nil,
+		autometrics.WithService("web-server"),
+		autometrics.WithMeterName("web-server"),
+		autometrics.WithCommit("anySHA"),
+		autometrics.WithVersion("2.1.37"),
 	)
 	http.Handle("/metrics", promhttp.Handler())
 }
@@ -121,28 +128,98 @@ This is the shortest way to initialize and expose the metrics that autometrics w
 You're set! You can now start your app and preview the metrics.
 
 </Steps>
+</Tab>
 
-## Viewing the metrics
+<Tab>
 
-### Using Autometrics Explorer
-<PreviewMetricsInExplorerSnippet/>
+<Steps>
 
-### Configure your Prometheus
+### Import the library in your code
 
-Make sure your Prometheus is configured correctly to find the metrics.
+In the main entrypoint of your program, add the package:
 
-See the [Configuring Prometheus](/deploying-prometheus) section for deploy target-specific instructions. 
+```go filename="main.go"
+import (
+	autometrics "github.com/autometrics-dev/autometrics-go/otel/autometrics"
+)
+```
 
-Example configuration:
+And then in your main function initialize the metrics:
 
-```yaml filename="prometheus.yml"
-scrape_configs:
-  - job_name: my-app
-    metrics_path: /metrics
-    static_configs:
-      # Replace the port with the port your app listens on
-      - targets: ['<host>:<port>']
-    # For a real deployment, you would want the scrape interval to be
-    # longer but for testing, you want the data to show up quickly
-    scrape_interval: 200ms
+```go filename="main.go"
+	autometrics.Init(
+		autometrics.WithService("myApp"),
+		autometrics.WithMeterName("myApp/v2/prod"),
+		autometrics.WithCommit("anySHA"),
+		autometrics.WithVersion("2.1.37"),
+	)
 ```
+
+### Add `go:generate autometrics --otel` to your code
+
+The manual changes you need to do are:
+
+```go filename="main.go"
+//go:generate autometrics --otel
+
+//autometrics:doc
+func RouteHandler(args interface{}) (err error) { // Name the error return value; this is an optional but recommended change
+        // ...
+        return nil
+}
+```
+
+<Callout>
+If you want the generated metrics to contain the function success rate, you must name the error return value. This is why we recommend to name the error value you return for the function you want to instrument.
+</Callout>
+
+### Generate the documentation and instrumentation code
+
+Install the go generator using `go install` as usual:
+
+```bash filename="Shell"
+go install https://github.com/autometrics-dev/autometrics-go/cmd/autometrics@latest
+```
+
+Once you've done this, the `autometrics` generator takes care of the rest, and you can
+simply call `go generate` with an optional environment variable:
+
+```bash filename="Shell"
+AM_PROMETHEUS_URL=http://localhost:9090/ go generate ./...
+```
+
+The generator will augment your doc comment to add quick links to metrics (using the Prometheus URL as base URL), and add a unique defer statement that will take care of instrumenting your code.
+
+The environment variable `AM_PROMETHEUS_URL` controls the base URL of the instance that is scraping the deployed version of your code. Having an environment variable means you can change the generated links without touching your code. Default value: `http://localhost:9090/`.
+
+<Callout>
+If you do not want to have lengthy documentation generated on top of the function, you can use `//autometrics:inst` annotation instead of `//autometrics:doc`.
+</Callout>
+
+### Push metrics to the OpenTelemetry collector
+
+If you have an OTLP collector setup with an accessible URL, then you can directly push your metrics to it by passing the relevant `WithPush...` options to `autometrics.Init`:
+
+```go {6-11}
+shutdown, err := autometrics.Init(
+		autometrics.WithService("myApp"),
+		autometrics.WithMeterName("myApp/v2/prod"),
+		autometrics.WithCommit("anySHA"),
+		autometrics.WithVersion("2.1.37"),
+		autometrics.WithPushCollectorURL("https://collector.example.com"),
+		autometrics.WithPushJobName("instance_2"), // You can leave the JobName out to let autometrics generate one
+		autometrics.WithPushPeriod(1 * time.Second),
+		autometrics.WithPushTimeout(500 * time.Millisecond),
+	)
+```
+
+</Steps>
+</Tab>
+
+</Tabs>
+
+## Viewing the metrics
+
+### Using Autometrics Explorer
+<PreviewMetricsInExplorerSnippet/>
+
diff --git a/src/pages/python/quickstart.mdx b/src/pages/python/quickstart.mdx
@@ -22,15 +22,50 @@ def create_user(name):
    # ...
 ```
 
-### Set the metrics collection library (optional)
+### Configure metrics exporting
 
-Use the environment variable `AUTOMETRICS_TRACKER` to set the metrics collection
-library. The default is `OPEN_TELEMETRY`.
+You can configure `autometrics` to export using either Prometheus or OpenTelemetry libraries by calling the `init` function:
 
-Options:
-- `OPEN_TELEMETRY` - uses `opentelemetry` to collect and expose metrics
-- `PROMETHEUS` - uses `prometheus_client` to collect and expose metrics
+<Tabs items={["Using Prometheus client", "Using OpenTelemetry"]}> 
 
+<Tab>
+
+Autometrics supports exporting metrics to Prometheus via the Prometheus Python client. This example uses the Prometheus Python client, available settings are same as the Prometheus Python client. By default, the Prometheus exporter will expose metrics on port 9464. 
+
+```python
+from autometrics import autometrics, init
+
+init(
+    tracker="prometheus",
+    exporter={
+        "type": "prometheus",
+        "port": 9464,
+    },
+    service_name="my-service",
+)
+```
+</Tab>
+
+<Tab>
+
+Autometrics supports exporting metrics to OTLP collectors via gRPC and HTTP transports. This example uses the HTTP transport, available settings are similar to the OpenTelemetry Python SDK. By default, the OTLP exporter will send metrics to `localhost:4318`.
+
+```python
+from autometrics import autometrics, init
+
+init(
+    exporter={
+        "type": "otlp-proto-http",
+        "endpoint": "http://your-otlp-endpoint",
+        "push_interval": 1000,
+    },
+    service_name="otlp-exporter",
+)
+```
+
+</Tab>
+
+</Tabs>
 </Steps>
 
 ## Viewing your metrics
diff --git a/src/pages/rust/quickstart.mdx b/src/pages/rust/quickstart.mdx
@@ -8,13 +8,15 @@ import PreviewMetricsInExplorerSnippet from "@/snippets/preview-in-am-explorer.m
 <Steps>
 ### Add Autometrics
 
+Add the `autometrics` crate dependency using `cargo`:
+
 ```bash copy
 cargo add autometrics
 ```
 
 ### Add the Autometrics macro
 
-Add the `#[autometrics]` to the functions you want to instrument with metrics
+Add the `#[autometrics]` macro to the functions you want to instrument with metrics
 
 ```rust
 use autometrics::autometrics;
@@ -27,7 +29,7 @@ pub async fn create_user() {
 
 ### Export the metrics
 
-<Tabs items={['Expose a endpoint for Prometheus', 'Push to a OpenTelemetry collector']}>
+<Tabs items={['Expose an endpoint for Prometheus', 'Push to a OpenTelemetry collector']}>
     <Tab>
         <Callout type="info">
             If you're already using Prometheus metrics in your app, you can skip this step. You only need to configure Autometrics to use the same underlying metrics collection library as your existing Prometheus metrics. See [Metrics Libraries](https://docs.rs/autometrics/latest/autometrics/#metrics-libraries) for more information in the API reference.
