[WIP] STAC-24067: use custom integrations for extending the interface

docs/latest/modules/en/nav.adoc

@@ -15,6 +15,7 @@
 * Monitors and alerts
 ** xref:use/alerting/k8s-monitors.adoc[Monitors]
 ** xref:use/alerting/kubernetes-monitors.adoc[Out of the box monitors for Kubernetes]
+*** xref:use/alerting/k8s-override-monitor-arguments.adoc[Override monitor arguments]
 ** xref:use/alerting/notifications/README.adoc[Notifications]
 *** xref:use/alerting/notifications/configure.adoc[Configure notifications]
 *** xref:use/alerting/notifications/channels/README.adoc[Notification channels]
@@ -23,19 +24,22 @@
 **** xref:use/alerting/notifications/channels/webhook.adoc[Webhook]
 **** xref:use/alerting/notifications/channels/opsgenie.adoc[Opsgenie]
 *** xref:use/alerting/notifications/troubleshooting.adoc[Troubleshooting]
+ifndef::ss-ff-stackpacks2_enabled[]
 ** Customize
 *** xref:use/alerting/k8s-add-monitors-cli.adoc[Add a monitor using the CLI]
 *** xref:use/alerting/k8s-derived-state-monitors.adoc[Derived State monitors]
 *** xref:use/alerting/k8s-dynamic-threshold-monitors.adoc[Dynamic Threshold monitors]
-*** xref:use/alerting/k8s-override-monitor-arguments.adoc[Override monitor arguments]
 *** xref:use/alerting/k8s-write-remediation-guide.adoc[Write a remediation guide]
+endif::ss-ff-stackpacks2_enabled[]
 * Metrics
 ** xref:use/metrics/k8sTs-explore-metrics.adoc[Explore Metrics]
 ** xref:use/metrics/k8sTs-metric-reference.adoc[Metrics references]
+ifndef::ss-ff-stackpacks2_enabled[]
 ** Custom charts
 *** xref:use/metrics/k8s-add-charts.adoc[Adding custom charts to components]
 *** xref:use/metrics/k8s-writing-promql-for-charts.adoc[Writing PromQL queries for representative charts]
 *** xref:use/metrics/k8sTs-metrics-troubleshooting.adoc[Troubleshooting custom charts]
+endif::ss-ff-stackpacks2_enabled[]
 ** Advanced Metrics
 *** xref:use/metrics/k8s-stackstate-grafana-datasource.adoc[Grafana Datasource]
 *** xref:use/metrics/k8s-prometheus-remote-write.adoc[Prometheus remote_write]
@@ -93,6 +97,18 @@ ifdef::ss-ff-stackpacks2_enabled[]
 *** xref:setup/custom-integrations/otelmappings/getting-started.adoc[Getting Started]
 *** xref:setup/custom-integrations/otelmappings/schemas-ref.adoc[Schema Reference]
 *** xref:setup/custom-integrations/otelmappings/troubleshooting.adoc[Troubleshooting]
+** xref:setup/custom-integrations/metric-bindings/index.adoc[Metric Bindings]
+*** xref:setup/custom-integrations/metric-bindings/writing-promql.adoc[Writing PromQL]
+*** xref:setup/custom-integrations/metric-bindings/schemas-ref.adoc[Schema Reference]
+*** xref:setup/custom-integrations/metric-bindings/troubleshooting.adoc[Troubleshooting]
+*** xref:setup/custom-integrations/metric-bindings/cli.adoc[CLI Support]
+** xref:setup/custom-integrations/monitors/index.adoc[Monitors]
+*** xref:setup/custom-integrations/monitors/remediation-guide.adoc[Write a remediation guide]
+*** xref:setup/custom-integrations/monitors/schemas-ref.adoc[Schema Reference]
+*** xref:setup/custom-integrations/monitors/troubleshooting.adoc[Troubleshooting]
+*** xref:setup/custom-integrations/monitors/cli.adoc[CLI Support]
+*** xref:setup/custom-integrations/monitors/derived-state-monitors.adoc[Derived State monitors]
+*** xref:setup/custom-integrations/monitors/dynamic-threshold-monitors.adoc[Dynamic Threshold monitors]
 endif::ss-ff-stackpacks2_enabled[]
 * Open Telemetry
 ** xref:setup/otel/overview.adoc[Overview]

docs/latest/modules/en/pages/setup/custom-integrations/develop.adoc

@@ -17,7 +17,7 @@ As a developer, you want to integrate your technology with {stackstate-product-n
 
 - Access to the xref:/setup/cli/cli-sts.adoc[StackPack CLI]
 - Feature flag enabled:
-
++
 [source,bash]
 ----
 export STS_EXPERIMENTAL_STACKPACK=true
@@ -26,10 +26,11 @@ export STS_EXPERIMENTAL_STACKPACK=true
 
 == How to Develop a Custom Integration (StackPack)
 
-. *Scaffold a New StackPack*
-+
+=== Scaffold a New StackPack
+
 The `scaffold` subcommand creates a new StackPack project structure from configurable templates, streamlining the initial setup process for StackPack development. The command supports both local directory templates and GitHub-hosted templates.
-Create a new StackPack project using the CLI:
+
+- Create a new StackPack project using the CLI:
 +
 [source,bash]
 ----
@@ -79,27 +80,26 @@ Next steps:
 ----
 sts stackpack scaffold --name my-stackpack --template-local-dir ./templates --template-name webapp
 ----
-+
 
 
-. *Review and Customize*
-+
+=== Review and Customize
+
 - Review the generated files in the target directory.
 - Edit `stackpack.yaml` and other files to define your integration logic.
   * Integrating data. To map components and ingest metrics see xref:setup/custom-integrations/otelmappings/README.adoc[Adding Otel Telemetry Mappings]
-  * xref:use/alerting/k8s-add-monitors-cli.adoc[Adding Monitors]
-  * xref:use/metrics/k8s-add-charts.adoc[Adding Metric Bindings]
+  * xref:setup/custom-integrations/monitors/index.adoc[Adding Monitors]
+  * xref:setup/custom-integrations/metric-bindings/index.adoc[Adding Metric Bindings]
 
 [NOTE]
 ====
 The default: https://github.com/StackVista/stackpack-templates[stackvista/stackpack-templates] template is a great starting point as it contains examples for most of the extension points such as Monitors and Metric Bindings.
 ====
 
-. *Test Your StackPack*
-+
+=== Test Your StackPack
+
 The `test` subcommand command that streamlines the stackpack development workflow by automating the package → upload → install/upgrade sequence with automatic version management for testing iterations.
-Rapidly test your StackPack in a pre-production environment (requires a running Suse Observability instance):
 
+- Rapidly test your StackPack in a pre-production environment (requires a running Suse Observability instance):
 +
 [source,bash]
 ----
@@ -139,11 +139,11 @@ ID             | NAME | STATUS      | VERSION         | LAST UPDATED
 - The `test` subcommand packages, uploads, and installs your StackPack with a test version suffix.
 - Iterate on your StackPack, using the `test` command for rapid feedback, make changes and observe the install/upgrade process to be successfully executed. Review the ingested topology and telemetry in the Suse Observability UI.
 
-. *Package Your finished StackPack version*
-+
-The `package` subcommand that creates zip files from stackpack directories. This command packages all required stackpack files and directories into a properly named zip archive for distribution and deployment.
-Package your StackPack into a distributable zip:
+=== Package Your finished StackPack version
+
+The `package` subcommand creates a zip file from stackpack directories. This command packages all required stackpack files and directories into a properly named zip archive for distribution and deployment.
 
+- Package your StackPack into a distributable zip:
 +
 [source,bash]
 ----
@@ -161,16 +161,20 @@ Zip file: /Users/viliakov/Workspace/src/github/stackstate-cli/my-stackpack/my-st
 sts stackpack package -d ./my-stackpack -f my-custom-archive.zip
 ----
 
+=== Upload your StackPack
 
+The `upload` subcommand pushes the zip archive to a running {stackstate-product-name} instance.
 
-. *Upload your stackpack to your instance*
+- Upload the archive to {stackstate-product-name}:
 +
 [source,bash]
 ----
 sts stackpack upload -f ./my-stackpack-0.0.1.zip
 ✅ ✓ Stackpack uploaded successfully!
 ----
 
-. xref:/stackpacks/about-stackpacks.adoc#_install_or_uninstall_a_stackpack[Install or Upgrade your StackPack] via the {stackstate-product-name} stackpacks UI.
+=== Install the StackPack
+
+xref:/stackpacks/about-stackpacks.adoc#_install_or_uninstall_a_stackpack[Install or Upgrade your StackPack] via the {stackstate-product-name} stackpacks UI.
 
 endif::ss-ff-stackpacks2_enabled[]

docs/latest/modules/en/pages/setup/custom-integrations/metric-bindings/cli.adoc

@@ -0,0 +1,119 @@
+= Using the CLI for metric bindings
+:revdate: 2026-01-14
+:page-revdate: {revdate}
+:description: SUSE Observability
+
+== Overview
+
+You can use the {stackstate-product-name} CLI to inspect and modify metric bindings.  These are handled like other settings using the `sts settings` command.
+
+== Inspecting Metric Bindings
+
+=== Listing Metric Bindings
+
+The `sts settings` command can list all metric bindings:
+
+[,bash]
+----
+sts settings list --type MetricBinding
+TYPE          | ID              | IDENTIFIER         | NAME               | OWNED BY           | LAST UPDATED        
+MetricBinding | 190567588459765 | urn:stackpack:kube | .NET GC Allocated  | urn:stackpack:kube | Sun Jan 11 01:28:2
+              |                 | rnetes-v2:shared:m |                    | rnetes-v2:shared   | 8 2026 CET        
+              |                 | etric-binding:pod: |                    |                    |                   
+              |                 | dotnet-gc-allocate |                    |                    |                   
+              |                 | d                  |                    |                    |                   
+MetricBinding | 247972504900226 | urn:stackpack:kube | .NET GC Allocated  | urn:stackpack:kube | Sun Jan 11 01:28:2
+              |                 | rnetes-v2:shared:m |                    | rnetes-v2:shared   | 8 2026 CET        
+              |                 | etric-binding:depl |                    |                    |                   
+              |                 | oyment:dotnet-gc-a |                    |                    |                   
+              |                 | llocated           |                    |                    |                   
+MetricBinding | 109239589408271 | urn:stackpack:open | .NET GC Allocated  | urn:stackpack:open | Wed Jan 7 00:20:48
+              |                 | -telemetry:shared: |                    | -telemetry:shared  |  2026 CET         
+              |                 | metric-binding:ser |                    |                    |                   
+              |                 | vice:dotnet-gc-all |                    |                    |                   
+              |                 | ocated             |                    |                    |                   
+...
+----
+
+=== Describing Metric Bindings
+
+You can get the definition of an existing metric binding by using the `describe` command:
+
+[,bash]
+----
+sts settings describe --ids 190567588459765
+_version: 1.0.93                                                                                                     
+nodes:
+- _type: MetricBinding
+  chartType: line
+  description: Bytes allocated to GC Heap
+  enabled: true
+  id: -1
+  identifier: urn:stackpack:kubernetes-v2:shared:metric-binding:pod:dotnet-gc-allocated
+  layout:
+    metricPerspective:
+      section: GC
+      tab: .NET
+      weight: 3
+  name: .NET GC Allocated
+  priority: high
+  queries:
+  - alias: allocated
+    expression: rate(process_runtime_dotnet_gc_allocations_size_bytes_total{k8s_cluster_name="${tags.cluster-name}", k8s_namespace_name="${tags.namespace}", k8s_pod_name="${name}"}[${__rate_interval}])
+  scope: (label = "stackpack:kubernetes" and type = "pod")
+  unit: bytes(IEC)
+timestamp: 2026-01-14T13:11:07.575662922Z[Etc/UTC]
+----
+
+== Modifying Metric Bindings
+
+[NOTE]
+====
+The recommended way of working is to store metric bindings (and any other custom resources created in {stackstate-product-name}) as YAML files in xref:/setup/custom-integrations/overview.adoc[a StackPack]. From there changes can be manually applied or it can be fully automated by using the SUSE Observability CLI in a CI/CD system like GitHub actions or GitLab pipelines.
+====
+
+=== Create/update a Metric Binding
+Create a file `metric-bindings.yaml` that looks like this:
+
+[source,bash]
+----
+nodes:
+- _type: MetricBinding
+  chartType: line
+  enabled: true
+  tags: {}
+  unit: short
+  name: Replica counts
+  priority: MEDIUM
+  identifier: urn:stackpack:my-stackpack:metric-binding:my-deployment-replica-counts
+  queries:
+    - expression: max_over_time(kubernetes_state_deployment_replicas{cluster_name="${tags.cluster-name}", namespace="${tags.namespace}", deployment="${name}"}[${__interval}])
+      alias: Total replicas
+  scope: type = "deployment" and label = "stackpack:kubernetes"
+----
+
+Use the xref:/setup/cli/cli-sts.adoc[SUSE Observability CLI] to create the metric binding:
+
+[,bash]
+----
+sts settings apply -f metric-bindings.yaml
+----
+
+Verify the results in SUSE Observability by opening the metrics perspective for a deployment. If you're not happy with the result simply change the metric binding in the YAML file and run the command again to update it. The list of nodes supports adding many metric bindings. Simply add another metric binding entry to the YAML array using the same steps as before.
+
+[CAUTION]
+====
+The identifier is used as the unique key of a metric binding. Changing the identifier will create a new metric binding instead of updating the existing one.
+====
+
+=== Delete a Metric Binding
+
+Finally to delete a metric binding use
+
+[,bash]
+----
+sts settings delete --ids <id>
+----
+
+The `<id>` in this command isn't the identifier but the number in the `Id` column of the `sts settings list` output.
+