Move usage_reporting under telemetry.hive and reuse options (#668)

**Before**

```yaml
usage_reporting:
  enabled: true
  access_token: "your-hive-token" # Duplicated
  target_id: "org/project/target" # Duplicated
  # Client identification was tied only to usage reporting
  client_name_header: "x-client-name"
  client_version_header: "x-client-version"
  sample_rate: "50%"
  exclude: ["IntrospectionQuery"]

telemetry:
  hive:
    token: "your-hive-token" # Duplicated
    target: "org/project/target" # Duplicated
    tracing:
      enabled: true
```

**After**

```yaml
telemetry:
  # Client identification is now global for all telemetry (traces, usage, etc.)
  client_identification:
    name_header: "x-client-name"
    version_header: "x-client-version"
    
  hive:
    # Credentials are defined once and shared by both usage and tracing
    token: "your-hive-token"
    target: "org/project/target"
    
    usage_reporting:
      enabled: true
      sample_rate: "50%"
      exclude: ["IntrospectionQuery"]
      
    tracing:
      enabled: true
```

Author: kamilkisiela

.changeset/unify-hive-telemetry-config.md

@@ -0,0 +1,40 @@
+---
+config: minor
+router: minor
+internal: minor
+---
+
+# Unified Hive Telemetry Configuration
+
+Refactored the configuration structure to unify Hive-specific telemetry (tracing and usage reporting) and centralize client identification.
+
+- **Unified Hive Config**: Moved `usage_reporting` under `telemetry.hive.usage`. Usage reporting now shares the `token` and `target` configuration with Hive tracing, eliminating redundant settings.
+- **Centralized Client Identification**: Introduced `telemetry.client_identification` to define client name and version headers once. These are now propagated to both OpenTelemetry spans and Hive usage reports.
+- **Enhanced Expression Support**: Both Hive token and target ID now support VRL expressions for usage reporting, matching the existing behavior of tracing.
+
+### Breaking Changes:
+
+The top-level `usage_reporting` block has been moved. 
+
+**Before:**
+```yaml
+usage_reporting:
+  enabled: true
+  access_token: "..."
+  target_id: "..."
+  client_name_header: "..."
+  client_version_header: "..."
+```
+
+**After:**
+```yaml
+telemetry:
+  client_identification:
+    name_header: "..."
+    version_header: "..."
+  hive:
+    token: "..."
+    target: "..."
+    usage:
+      enabled: true
+```

Cargo.lock

@@ -19,7 +19,7 @@ use crate::{
         probes::{health_check_handler, readiness_check_handler},
     },
     jwt::JwtAuthRuntime,
-    pipeline::{graphql_request_handler, usage_reporting::init_hive_user_agent},
+    pipeline::{graphql_request_handler, usage_reporting::init_hive_usage_agent},
     telemetry::HeaderExtractor,
 };
 
@@ -129,12 +129,11 @@ pub async fn configure_app_from_config(
         false => None,
     };
 
-    let hive_usage_agent = match router_config.usage_reporting.enabled {
-        true => Some(init_hive_user_agent(
-            bg_tasks_manager,
-            &router_config.usage_reporting,
-        )?),
-        false => None,
+    let hive_usage_agent = match router_config.telemetry.hive.as_ref() {
+        Some(hive_config) if hive_config.usage_reporting.enabled => {
+            Some(init_hive_usage_agent(bg_tasks_manager, hive_config)?)
+        }
+        _ => None,
     };
 
     let router_config_arc = Arc::new(router_config);

bin/router/src/lib.rs

@@ -154,6 +154,26 @@ pub async fn execute_pipeline(
     let operation_span = GraphQLOperationSpan::new();
     async {
         let start = Instant::now();
+        let client_name = req
+            .headers()
+            .get(
+                &shared_state
+                    .router_config
+                    .telemetry
+                    .client_identification
+                    .name_header,
+            )
+            .and_then(|v| v.to_str().ok());
+        let client_version = req
+            .headers()
+            .get(
+                &shared_state
+                    .router_config
+                    .telemetry
+                    .client_identification
+                    .version_header,
+            )
+            .and_then(|v| v.to_str().ok());
         perform_csrf_prevention(req, &shared_state.router_config.csrf)?;
         let jwt_request_details = match &shared_state.jwt_auth_runtime {
             Some(jwt_auth_runtime) => match jwt_auth_runtime
@@ -179,6 +199,7 @@ pub async fn execute_pipeline(
 
         operation_span.record_document(&parser_payload.minified_document);
         operation_span.record_operation_identity((&parser_payload).into());
+        operation_span.record_client_identity(client_name, client_version);
         operation_span.record_hive_operation_hash(&parser_payload.hive_operation_hash);
 
         validate_operation_with_cache(supergraph, schema_state, shared_state, &parser_payload)
@@ -254,19 +275,29 @@ pub async fn execute_pipeline(
         )
         .await?;
 
-        if shared_state.router_config.usage_reporting.enabled {
-            if let Some(hive_usage_agent) = &shared_state.hive_usage_agent {
-                usage_reporting::collect_usage_report(
-                    supergraph.supergraph_schema.clone(),
-                    start.elapsed(),
-                    req,
-                    &client_request_details,
-                    hive_usage_agent,
-                    &shared_state.router_config.usage_reporting,
-                    &execution_result,
-                )
-                .await;
-            }
+        if let Some(hive_usage_agent) = &shared_state.hive_usage_agent {
+            usage_reporting::collect_usage_report(
+                supergraph.supergraph_schema.clone(),
+                start.elapsed(),
+                client_name,
+                client_version,
+                &client_request_details,
+                hive_usage_agent,
+                shared_state
+                    .router_config
+                    .telemetry
+                    .hive
+                    .as_ref()
+                    .map(|c| &c.usage_reporting)
+                    .expect(
+                        // SAFETY: According to `configure_app_from_config` in `bin/router/src/lib.rs`,
+                        // the UsageAgent is only created when usage reporting is enabled.
+                        // Thus, this expect should never panic.
+                        "Expected Usage Reporting options to be present when Hive Usage Agent is initialized",
+                    ),
+                &execution_result,
+            )
+            .await;
         }
 
         Ok(execution_result)

bin/router/src/pipeline/mod.rs

@@ -7,11 +7,15 @@ use async_trait::async_trait;
 use graphql_tools::parser::schema::Document;
 use hive_console_sdk::agent::usage_agent::{AgentError, UsageAgentExt};
 use hive_console_sdk::agent::usage_agent::{ExecutionReport, UsageAgent};
+use hive_router_config::telemetry::hive::{
+    is_slug_target_ref, is_uuid_target_ref, HiveTelemetryConfig,
+};
 use hive_router_config::usage_reporting::UsageReportingConfig;
+use hive_router_internal::telemetry::resolve_value_or_expression;
 use hive_router_plan_executor::execution::{
     client_request_details::ClientRequestDetails, plan::PlanExecutionOutput,
 };
-use ntex::web::HttpRequest;
+
 use rand::Rng;
 use tokio_util::sync::CancellationToken;
 
@@ -22,47 +26,71 @@ use crate::{
 
 #[derive(Debug, thiserror::Error)]
 pub enum UsageReportingError {
-    #[error("Usage Reporting - Access token is missing. Please provide it via 'HIVE_ACCESS_TOKEN' environment variable or under 'usage_reporting.access_token' in the configuration.")]
+    #[error("Usage Reporting - Access token is missing. Please provide it via 'HIVE_ACCESS_TOKEN' environment variable or under 'telemetry.hive.token' in the configuration.")]
     MissingAccessToken,
     #[error("Usage Reporting - Failed to initialize usage agent: {0}")]
     AgentCreationError(#[from] AgentError),
+    #[error("Usage Reporting - Configuration error: {0}")]
+    ConfigurationError(String),
 }
 
-pub fn init_hive_user_agent(
+pub fn init_hive_usage_agent(
     bg_tasks_manager: &mut BackgroundTasksManager,
-    usage_config: &UsageReportingConfig,
+    hive_config: &HiveTelemetryConfig,
 ) -> Result<UsageAgent, UsageReportingError> {
+    let usage_config = &hive_config.usage_reporting;
     let user_agent = format!("hive-router/{}", ROUTER_VERSION);
-    let access_token = usage_config
-        .access_token
-        .as_deref()
-        .ok_or(UsageReportingError::MissingAccessToken)?;
+    let access_token = match &hive_config.token {
+        Some(t) => resolve_value_or_expression(t, "Hive Telemetry token")
+            .map_err(|e| UsageReportingError::ConfigurationError(e.to_string()))?,
+        None => return Err(UsageReportingError::MissingAccessToken),
+    };
+
+    let target = match &hive_config.target {
+        Some(t) => Some(
+            resolve_value_or_expression(t, "Hive Telemetry target")
+                .map_err(|e| UsageReportingError::ConfigurationError(e.to_string()))?,
+        ),
+        None => None,
+    };
 
-    let mut agent = UsageAgent::builder()
+    if let Some(target) = &target {
+        if !is_uuid_target_ref(target) && !is_slug_target_ref(target) {
+            return Err(UsageReportingError::ConfigurationError(format!(
+                "Invalid Hive Telemetry target format: '{}'. It must be either in slug format '$organizationSlug/$projectSlug/$targetSlug' or UUID format 'a0f4c605-6541-4350-8cfe-b31f21a4bf80'",
+                target
+            )));
+        }
+    }
+
+    let mut agent_builder = UsageAgent::builder()
         .user_agent(user_agent)
         .endpoint(usage_config.endpoint.clone())
-        .token(access_token.to_string())
+        .token(access_token)
         .buffer_size(usage_config.buffer_size)
         .connect_timeout(usage_config.connect_timeout)
         .request_timeout(usage_config.request_timeout)
         .accept_invalid_certs(usage_config.accept_invalid_certs)
         .flush_interval(usage_config.flush_interval);
 
-    if let Some(target_id) = usage_config.target_id.as_ref() {
-        agent = agent.target_id(target_id.clone());
+    if let Some(target_id) = target {
+        agent_builder = agent_builder.target_id(target_id);
     }
 
-    let agent = agent.build()?;
+    let agent = agent_builder.build()?;
 
     bg_tasks_manager.register_task(agent.clone());
     Ok(agent)
 }
 
+// TODO: simplfy args
+#[allow(clippy::too_many_arguments)]
 #[inline]
 pub async fn collect_usage_report<'a>(
     schema: Arc<Document<'static, String>>,
     duration: Duration,
-    req: &HttpRequest,
+    client_name: Option<&str>,
+    client_version: Option<&str>,
     client_request_details: &ClientRequestDetails<'a, 'a>,
     hive_usage_agent: &UsageAgent,
     usage_config: &UsageReportingConfig,
@@ -79,16 +107,14 @@ pub async fn collect_usage_report<'a>(
     {
         return;
     }
-    let client_name = get_header_value(req, &usage_config.client_name_header);
-    let client_version = get_header_value(req, &usage_config.client_version_header);
     let timestamp = SystemTime::now()
         .duration_since(UNIX_EPOCH)
         .unwrap()
         .as_millis() as u64;
     let execution_report = ExecutionReport {
         schema,
-        client_name: client_name.map(|s| s.to_owned()),
-        client_version: client_version.map(|s| s.to_owned()),
+        client_name: client_name.map(|name| name.to_string()),
+        client_version: client_version.map(|version| version.to_string()),
         timestamp,
         duration,
         ok: execution_result.error_count == 0,
@@ -106,11 +132,6 @@ pub async fn collect_usage_report<'a>(
     }
 }
 
-#[inline]
-fn get_header_value<'req>(req: &'req HttpRequest, header_name: &str) -> Option<&'req str> {
-    req.headers().get(header_name).and_then(|v| v.to_str().ok())
-}
-
 #[async_trait]
 impl BackgroundTask for UsageAgent {
     fn id(&self) -> &str {