Review docs about embedding yace (prometheus-community#868)

Author: cristiangreco

README.md

@@ -113,7 +113,7 @@ To provide backwards compatibility, some of YACE's new features or breaking chan
 
 ## Installing and running
 
-Refer to the [installing guide](docs/install.md).
+Refer to the [installation guide](docs/installation.md).
 
 ## Authentication
 
@@ -278,31 +278,9 @@ This protects from the abuse of API requests that can cause extra billing in AWS
 The flag 'scraping-interval' defines the seconds between scrapes.
 The default value is 300.
 
-## Using YACE as a Go library
-
-It is possible to embed YACE in to an external application. This mode might be useful to you if you would like to scrape on demand or run in a stateless manner.
-
-The entrypoint to use YACE as a library is the `UpdateMetrics` func in [update.go](./pkg/exporter.go#L35) which requires,
-- `config`: this is the struct representation of the configuration defined in [Top Level Configuration](#top-level-configuration)
-- `registry`: any prometheus compatible registry where scraped AWS metrics will be written
-- `metricsPerQuery`: controls the same behavior defined by the CLI flag `metrics-per-query`
-- `labelsSnakeCase`: controls the same behavior defined by the CLI flag `labels-snake-case`
-- `cloudwatchSemaphore`/`tagSemaphore`: adjusts the concurrency of requests as defined by [Requests concurrency](#requests-concurrency). Pass in a different length channel to adjust behavior
-- `cache`
-  - Any implementation of the [SessionCache Interface](./pkg/session/sessions.go#L41)
-  - `session.NewSessionCache(config, <fips value>)` would be the default
-  - `<fips value>` is defined by the `fips` CLI flag
-- `observedMetricLabels`
-  - Prometheus requires that all metrics exported with the same key have the same labels
-  - This map will track all labels observed and ensure they are exported on all metrics with the same key in the provided `registry`
-  - You should provide the same instance of this map if you intend to re-use the `registry` between calls
-- `logger`
-  - Any implementation of the [Logger Interface](./pkg/logging/logger.go#L13)
-  - `logging.NewLogger(logrus.StandardLogger())` is an acceptable default
-
-The update definition also includes an exported slice of [Metrics](./pkg/exporter.go#L18) which includes AWS API call metrics. These can be registered with the provided `registry` if you want them
-included in the AWS scrape results. If you are using multiple instances of `registry` it might make more sense to register these metrics in the application using YACE as a library to better
-track them over the lifetime of the application.
+## Embedding YACE in your application
+
+YACE can be used as a library and embedded into your application, see the [embedding guide](docs/embedding.md).
 
 ## Troubleshooting / Debugging
 

docs/embedding.md

@@ -0,0 +1,8 @@
+# Embedding YACE in your application
+
+It is possible to embed YACE into an external Go application. This mode might be useful to you if you would like to scrape on demand or run in a stateless manner.
+
+See [`exporter.UpdateMetrics()`](https://pkg.go.dev/github.com/nerdswords/[email protected]/pkg#UpdateMetrics) for the documentation of the exporter entrypoint.
+
+Applications embedding YACE:
+- [Grafana Agent](https://github.com/grafana/agent/tree/release-v0.33/pkg/integrations/cloudwatch_exporter)

docs/install.md renamed to docs/installation.md

@@ -114,9 +114,20 @@ func EnableFeatureFlag(flags ...string) OptionsFunc {
 	}
 }
 
-// UpdateMetrics can be used to scrape metrics from AWS on demand using the provided parameters. Scraped metrics will be added to the provided registry and
-// any labels discovered during the scrape will be added to observedMetricLabels with their metric name as the key. Any errors encountered are not returned but
-// will be logged and will either fail the scrape or a partial metric result will be added to the registry.
+// UpdateMetrics is the entrypoint to scrape metrics from AWS on demand.
+//
+// Parameters are:
+// - `ctx`: a context for the request
+// - `config`: this is the struct representation of the configuration defined in top-level configuration
+// - `logger`: any implementation of the `Logger` interface
+// - `registry`: any prometheus compatible registry where scraped AWS metrics will be written
+// - `cache`: any implementation of the `SessionCache`
+// - `optFuncs`: (optional) any number of options funcs
+//
+// You can pre-register any of the default metrics with the provided `registry` if you want them
+// included in the AWS scrape results. If you are using multiple instances of `registry` it
+// might make more sense to register these metrics in the application using YACE as a library to better
+// track them over the lifetime of the application.
 func UpdateMetrics(
 	ctx context.Context,
 	logger logging.Logger,