misc: improved monitoring and telemetry docs

docs/self-hosting/guides/monitoring-telemetry.mdx

@@ -27,7 +27,9 @@ Both approaches provide the same metrics data in OTEL format, so you can choose
 - Access to deploy monitoring services (Prometheus, Grafana, etc.)
 - Basic understanding of Prometheus and Grafana
 
-## Environment Variables
+## Setup
+
+### Environment Variables
 
 Configure the following environment variables in your Infisical backend:
 
@@ -37,18 +39,10 @@ OTEL_TELEMETRY_COLLECTION_ENABLED=true
 
 # Choose export type: "prometheus" or "otlp"
 OTEL_EXPORT_TYPE=prometheus
-
-# For OTLP push mode, also configure:
-# OTEL_EXPORT_OTLP_ENDPOINT=http://otel-collector:4318/v1/metrics
-# OTEL_COLLECTOR_BASIC_AUTH_USERNAME=your_collector_username
-# OTEL_COLLECTOR_BASIC_AUTH_PASSWORD=your_collector_password
-# OTEL_OTLP_PUSH_INTERVAL=30000
 ```
 
-**Note**: The `OTEL_COLLECTOR_BASIC_AUTH_USERNAME` and `OTEL_COLLECTOR_BASIC_AUTH_PASSWORD` values must match the credentials configured in your OpenTelemetry Collector's `basicauth/server` extension. These are not hardcoded values - you configure them in your collector configuration file.
+<Tabs>
-
+  <Tab title="Pull-based Monitoring (Prometheus)">
-## Option 1: Pull-based Monitoring (Prometheus)
-
     This approach exposes metrics on port 9464 at the `/metrics` endpoint, allowing Prometheus to scrape the data. The metrics are exposed in Prometheus format but originate from OpenTelemetry instrumentation.
 
     ### Configuration
@@ -90,8 +84,8 @@ This approach exposes metrics on port 9464 at the `/metrics` endpoint, allowing
 
     ### Deployment Options
 
-#### Docker Compose
+    <Tabs>
-
+      <Tab title="Docker Compose">
         ```yaml
         services:
           prometheus:
@@ -111,9 +105,8 @@ services:
               - GF_SECURITY_ADMIN_USER=admin
               - GF_SECURITY_ADMIN_PASSWORD=admin
         ```
-
+      </Tab>
-#### Kubernetes
+      <Tab title="Kubernetes">
-
         ```yaml
         # prometheus-deployment.yaml
         apiVersion: apps/v1
@@ -157,9 +150,8 @@ spec:
               targetPort: 9090
           type: ClusterIP
         ```
-
+      </Tab>
-#### Helm
+      <Tab title="Helm">
-
         ```bash
         helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
         helm install prometheus prometheus-community/prometheus \
@@ -167,9 +159,11 @@ helm install prometheus prometheus-community/prometheus \
           --set server.config.scrape_configs[0].job_name=infisical \
           --set server.config.scrape_configs[0].static_configs[0].targets[0]=infisical-backend:9464
         ```
+      </Tab>
+    </Tabs>
 
-## Option 2: Push-based Monitoring (OTLP)
+  </Tab>
-
+  <Tab title="Push-based Monitoring (OTLP)">
     This approach sends metrics directly to an OpenTelemetry Collector via the OTLP protocol. This gives you the most flexibility as you can configure the collector to export to multiple backends simultaneously.
 
     ### Configuration
@@ -262,8 +256,8 @@ This approach sends metrics directly to an OpenTelemetry Collector via the OTLP
 
     ### Deployment Options
 
-#### Docker Compose
+    <Tabs>
-
+      <Tab title="Docker Compose">
         ```yaml
         services:
           otel-collector:
@@ -276,9 +270,8 @@ services:
             command:
               - "--config=/etc/otelcol-contrib/config.yaml"
         ```
-
+      </Tab>
-#### Kubernetes
+      <Tab title="Kubernetes">
-
         ```yaml
         # otel-collector-deployment.yaml
         apiVersion: apps/v1
@@ -309,15 +302,19 @@ spec:
                   configMap:
                     name: otel-collector-config
         ```
-
+      </Tab>
-#### Helm
+      <Tab title="Helm">
-
         ```bash
         helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
         helm install otel-collector open-telemetry/opentelemetry-collector \
           --set config.receivers.otlp.protocols.http.endpoint=0.0.0.0:4318 \
           --set config.exporters.prometheus.endpoint=0.0.0.0:8889
         ```
+      </Tab>
+    </Tabs>
+
+  </Tab>
+</Tabs>
 
 ## Available Metrics
 
@@ -327,13 +324,17 @@ Infisical exposes the following key metrics in OpenTelemetry format:
 
 These metrics track all HTTP API requests to Infisical, including request counts, latency, and errors. Use these to monitor overall API health, identify performance bottlenecks, and track usage patterns across users and machine identities.
 
-#### Total API Requests
+<AccordionGroup>
+  <Accordion title="Total API Requests">
+    **Metric Name**: `infisical.http.server.request.count`
 
-- **Metric Name**: `infisical.http.server.request.count`
+    **Type**: Counter
-- **Type**: Counter
+
-- **Unit**: `{request}`
+    **Unit**: `{request}`
-- **Description**: Total number of API requests to Infisical (covers both human users and machine identities)
+
-- **Attributes**:
+    **Description**: Total number of API requests to Infisical (covers both human users and machine identities)
+
+    **Attributes**:
       - `infisical.organization.id` (string): Organization ID
       - `infisical.organization.name` (string): Organization name (e.g., "Platform Engineering Team")
       - `infisical.user.id` (string, optional): User ID if human user
@@ -348,15 +349,20 @@ These metrics track all HTTP API requests to Infisical, including request counts
       - `infisical.project.name` (string, optional): Project name
       - `user_agent.original` (string, optional): User agent string
       - `client.address` (string, optional): IP address
+  </Accordion>
 
-#### Request Duration
+  <Accordion title="Request Duration">
+    **Metric Name**: `infisical.http.server.request.duration`
 
-- **Metric Name**: `infisical.http.server.request.duration`
+    **Type**: Histogram
-- **Type**: Histogram
+
-- **Unit**: `s` (seconds)
+    **Unit**: `s` (seconds)
-- **Description**: API request latency
+
-- **Buckets**: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+    **Description**: API request latency
-- **Attributes**:
+
+    **Buckets**: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+
+    **Attributes**:
       - `infisical.organization.id` (string): Organization ID
       - `infisical.organization.name` (string): Organization name
       - `infisical.user.id` (string, optional): User ID if human user
@@ -368,14 +374,18 @@ These metrics track all HTTP API requests to Infisical, including request counts
       - `http.response.status_code` (int): HTTP status code
       - `infisical.project.id` (string, optional): Project ID
       - `infisical.project.name` (string, optional): Project name
+  </Accordion>
 
-#### API Errors by Actor
+  <Accordion title="API Errors by Actor">
+    **Metric Name**: `infisical.http.server.error.count`
     
-- **Metric Name**: `infisical.http.server.error.count`
+    **Type**: Counter
-- **Type**: Counter
+    
-- **Unit**: `{error}`
+    **Unit**: `{error}`
-- **Description**: API errors grouped by actor (for identifying misconfigured services)
+    
-- **Attributes**:
+    **Description**: API errors grouped by actor (for identifying misconfigured services)
+    
+    **Attributes**:
       - `infisical.organization.id` (string): Organization ID
       - `infisical.organization.name` (string): Organization name
       - `infisical.user.id` (string, optional): User ID if human
@@ -389,18 +399,24 @@ These metrics track all HTTP API requests to Infisical, including request counts
       - `infisical.project.name` (string, optional): Project name
       - `client.address` (string, optional): IP address
       - `user_agent.original` (string, optional): User agent information
+  </Accordion>
+</AccordionGroup>
 
 ### Secret Operations Metrics
 
 These metrics provide visibility into secret access patterns, helping you understand which secrets are being accessed, by whom, and from where. Essential for security auditing and access pattern analysis.
 
-#### Secret Read Operations
+<AccordionGroup>
+  <Accordion title="Secret Read Operations">
+    **Metric Name**: `infisical.secret.read.count`
     
-- **Metric Name**: `infisical.secret.read.count`
+    **Type**: Counter
-- **Type**: Counter
+    
-- **Unit**: `{operation}`
+    **Unit**: `{operation}`
-- **Description**: Number of secret read operations
+    
-- **Attributes**:
+    **Description**: Number of secret read operations
+    
+    **Attributes**:
       - `infisical.organization.id` (string): Organization ID
       - `infisical.organization.name` (string): Organization name
       - `infisical.project.id` (string): Project ID
@@ -414,18 +430,24 @@ These metrics provide visibility into secret access patterns, helping you unders
       - `infisical.identity.name` (string, optional): Machine identity name
       - `user_agent.original` (string, optional): User agent/SDK information
       - `client.address` (string, optional): IP address
+  </Accordion>
+</AccordionGroup>
 
 ### Authentication Metrics
 
 These metrics track authentication attempts and outcomes, enabling you to monitor login success rates, detect potential security threats, and identify authentication issues.
 
-#### Login Attempts
+<AccordionGroup>
+  <Accordion title="Login Attempts">
+    **Metric Name**: `infisical.auth.attempt.count`
     
-- **Metric Name**: `infisical.auth.attempt.count`
+    **Type**: Counter
-- **Type**: Counter
+    
-- **Unit**: `{attempt}`
+    **Unit**: `{attempt}`
-- **Description**: Authentication attempts (both successful and failed)
+    
-- **Attributes**:
+    **Description**: Authentication attempts (both successful and failed)
+    
+    **Attributes**:
       - `infisical.organization.id` (string): Organization ID
       - `infisical.organization.name` (string): Organization name
       - `infisical.user.id` (string, optional): User ID if human (if identifiable)
@@ -438,43 +460,74 @@ These metrics track authentication attempts and outcomes, enabling you to monito
       - `client.address` (string): IP address
       - `user_agent.original` (string, optional): User agent/client information
       - `infisical.auth.attempt.username` (string, optional): Attempted username/email (if available)
+  </Accordion>
+</AccordionGroup>
 
 ### Legacy Metrics
 
 These metrics are from the previous instrumentation and may be deprecated in future versions. Consider migrating to the new Core API Metrics for more comprehensive observability.
 
-- `API_latency` - API request latency histogram in milliseconds (Labels: `route`, `method`, `statusCode`)
+<AccordionGroup>
-- `API_errors` - API error count histogram (Labels: `route`, `method`, `type`, `name`)
+  <Accordion title="API_latency">
+    API request latency histogram in milliseconds
+    
+    - **Labels**: `route`, `method`, `statusCode`
+  </Accordion>
+  
+  <Accordion title="API_errors">
+    API error count histogram
+    
+    - **Labels**: `route`, `method`, `type`, `name`
+  </Accordion>
+</AccordionGroup>
 
 ### Integration & Secret Sync Metrics
 
 These metrics monitor secret synchronization operations between Infisical and external systems, helping you track sync health, identify integration failures, and troubleshoot connectivity issues.
 
-- `integration_secret_sync_errors` - Integration secret sync error count
+<AccordionGroup>
+  <Accordion title="integration_secret_sync_errors">
+    Integration secret sync error count
 
     - **Labels**: `version`, `integration`, `integrationId`, `type`, `status`, `name`, `projectId`
     - **Example**: Monitor integration sync failures across different services
+  </Accordion>
 
-- `secret_sync_sync_secrets_errors` - Secret sync operation error count
+  <Accordion title="secret_sync_sync_secrets_errors">
+    Secret sync operation error count
 
     - **Labels**: `version`, `destination`, `syncId`, `projectId`, `type`, `status`, `name`
     - **Example**: Track secret sync failures to external systems
+  </Accordion>
 
-- `secret_sync_import_secrets_errors` - Secret import operation error count
+  <Accordion title="secret_sync_import_secrets_errors">
+    Secret import operation error count
 
     - **Labels**: `version`, `destination`, `syncId`, `projectId`, `type`, `status`, `name`
     - **Example**: Monitor secret import failures
+  </Accordion>
+
+  <Accordion title="secret_sync_remove_secrets_errors">
+    Secret removal operation error count
     
-- `secret_sync_remove_secrets_errors` - Secret removal operation error count
     - **Labels**: `version`, `destination`, `syncId`, `projectId`, `type`, `status`, `name`
     - **Example**: Track secret removal operation failures
+  </Accordion>
+</AccordionGroup>
 
 ### System Metrics
 
 These low-level HTTP metrics are automatically collected by OpenTelemetry's instrumentation layer, providing baseline performance data for all HTTP traffic.
 
-- `http_server_duration` - HTTP server request duration metrics (histogram buckets, count, sum)
+<AccordionGroup>
-- `http_client_duration` - HTTP client request duration metrics (histogram buckets, count, sum)
+  <Accordion title="http_server_duration">
+    HTTP server request duration metrics (histogram buckets, count, sum)
+  </Accordion>
+  
+  <Accordion title="http_client_duration">
+    HTTP client request duration metrics (histogram buckets, count, sum)
+  </Accordion>
+</AccordionGroup>
 
 ## Troubleshooting