feat(logging): improve calculate_records instrumentation and example guidance

Enhanced debug logging in calculate_records() to meet coding standards and
improved example documentation to guide users toward proper setup.

Logging Improvements (calculate_records):
- Added calc_count to #[instrument] fields for span context
- Added structured logging for calc_expression_count and rollback_on_failure
- Added debug logs when using optional parameters (session_id, gdb_version)
- Added response_length debug log after receiving response
- Added detailed error logging with response preview on deserialization failure
- Added edit_moment to completion info log

Standards Met:
✅ #[instrument] with appropriate skip and fields
✅ Structured context fields (layer_id, calc_count)
✅ Debug events at key points (request, response, optional params)
✅ Error logging before returning (with response preview for debugging)
✅ Info logging on completion with all result fields

Example Improvements:
- Changed FEATURE_SERVICE_URL from optional to required
- Added comprehensive setup instructions for creating own feature service
- Explained why public sample servers don't work (reject API key editing)
- Added troubleshooting section for common errors (498, 400)
- Added warning about data modification before execution
- Improved error message formatting with clear action steps

User Experience:
- Running without FEATURE_SERVICE_URL now shows helpful setup guide
- Debug mode (RUST_LOG=debug) provides detailed request/response tracing
- Clear explanation of authentication requirements
- Step-by-step ArcGIS Online setup instructions

Files Modified:
- src/services/feature/client/edit.rs - Enhanced calculate_records logging
- examples/enterprise/feature_service_field_calculations.rs - Improved docs and validation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: crumplecup

examples/enterprise/feature_service_field_calculations.rs

@@ -22,19 +22,42 @@
 //!
 //! # Usage
 //!
-//! This example requires authentication with a feature service that allows editing.
-//! Set the following environment variables in your `.env` file:
+//! This example requires authentication with a feature service that you own and control.
+//! **Important**: Public sample servers do not accept API key editing operations.
+//!
+//! ## Setup
+//!
+//! 1. Create your own hosted feature service in ArcGIS Online:
+//!    - Log into https://www.arcgis.com
+//!    - Go to Content → New Item → Feature Layer
+//!    - Create a simple layer with text fields (e.g., "eventtype", "description")
+//!    - Enable editing in the settings
+//!    - Copy the Feature Service URL (ends with /FeatureServer)
+//!
+//! 2. Set environment variables in your `.env` file:
 //!
 //! ```env
 //! ARCGIS_FEATURES_KEY=your_api_key_with_edit_privileges
-//! FEATURE_SERVICE_URL=https://your-server/arcgis/rest/services/YourService/FeatureServer
+//! FEATURE_SERVICE_URL=https://services.arcgis.com/YOUR_ORG/arcgis/rest/services/YOUR_SERVICE/FeatureServer
 //! LAYER_ID=0
 //! ```
 //!
-//! Run with:
+//! 3. Run the example:
+//!
 //! ```bash
 //! cargo run --example feature_service_field_calculations
+//!
+//! # With debug logging to see request/response details:
+//! RUST_LOG=debug cargo run --example feature_service_field_calculations
 //! ```
+//!
+//! ## Troubleshooting
+//!
+//! - **Error 498 "Invalid Token"**: Your API key doesn't have permissions for this service.
+//!   Make sure you own the service and the API key has editing privileges.
+//!
+//! - **Error 400 "Field does not exist"**: The layer schema doesn't match the example.
+//!   Update the field names in the example to match your layer's fields.
 
 use anyhow::{Context, Result};
 use arcgis::{
@@ -68,12 +91,21 @@ async fn main() -> Result<()> {
          This key is used for feature editing operations (add/update/delete/calculate).",
     )?;
 
-    // Get optional service URL and layer ID from environment
-    let service_url = std::env::var("FEATURE_SERVICE_URL").unwrap_or_else(|_| {
-        // Default to a public editable test service (if available)
-        // Note: In production, use a service you control
-        "https://sampleserver6.arcgisonline.com/arcgis/rest/services/LocalGovernment/Events/FeatureServer".to_string()
-    });
+    // Get service URL - REQUIRED for this example
+    let service_url = std::env::var("FEATURE_SERVICE_URL").context(
+        "FEATURE_SERVICE_URL not set. This example requires a feature service you own.\n\
+         \n\
+         Public sample servers reject API key editing operations.\n\
+         \n\
+         To run this example:\n\
+         1. Create a hosted feature service in ArcGIS Online (https://www.arcgis.com)\n\
+         2. Enable editing and add some text fields (eventtype, description)\n\
+         3. Set FEATURE_SERVICE_URL in .env:\n\
+         \n\
+         FEATURE_SERVICE_URL=https://services.arcgis.com/YOUR_ORG/arcgis/rest/services/YOUR_SERVICE/FeatureServer\n\
+         \n\
+         See example documentation for detailed setup instructions.",
+    )?;
 
     let layer_id_str = std::env::var("LAYER_ID").unwrap_or_else(|_| "0".to_string());
     let layer_id = LayerId::new(layer_id_str.parse::<u32>()?);
@@ -85,6 +117,10 @@ async fn main() -> Result<()> {
 
     tracing::info!("Connected to feature service: {}", service_url);
     tracing::info!("Using layer ID: {}", layer_id);
+    tracing::info!("");
+    tracing::info!("⚠️  Note: This example will add, modify, and delete features.");
+    tracing::info!("   Make sure you have a backup if using a production service.");
+    tracing::info!("");
 
     // ========================================
     // Setup: Add test features for calculation

src/services/feature/client/edit.rs

@@ -533,7 +533,7 @@ impl<'a> FeatureServiceClient<'a> {
     /// # Ok(())
     /// # }
     /// ```
-    #[instrument(skip(self, where_clause, calc_expression, options), fields(layer_id = %layer_id))]
+    #[instrument(skip(self, where_clause, calc_expression, options), fields(layer_id = %layer_id, calc_count = calc_expression.len()))]
     pub async fn calculate_records(
         &self,
         layer_id: LayerId,
@@ -548,7 +548,13 @@ impl<'a> FeatureServiceClient<'a> {
         let where_str = where_clause.into();
         let calc_json = serde_json::to_string(&calc_expression)?;
 
-        tracing::debug!(url = %url, where_clause = %where_str, "Sending calculate request");
+        tracing::debug!(
+            url = %url,
+            where_clause = %where_str,
+            calc_expression_count = calc_expression.len(),
+            rollback_on_failure = ?options.rollback_on_failure,
+            "Sending calculate request"
+        );
 
         let mut form = vec![
             ("where", where_str.as_str()),
@@ -559,9 +565,11 @@ impl<'a> FeatureServiceClient<'a> {
         // Add optional parameters
         let session_id_str = options.session_id.as_ref().map(|s| s.to_string());
         if let Some(ref session_id) = session_id_str {
+            tracing::debug!(session_id = %session_id, "Using edit session");
             form.push(("sessionId", session_id.as_str()));
         }
         if let Some(ref gdb_version) = options.gdb_version {
+            tracing::debug!(gdb_version = %gdb_version, "Using geodatabase version");
             form.push(("gdbVersion", gdb_version.as_str()));
         }
         if let Some(rollback) = options.rollback_on_failure {
@@ -592,12 +600,26 @@ impl<'a> FeatureServiceClient<'a> {
         }
 
         let response_text = response.text().await?;
+        tracing::debug!(
+            response_length = response_text.len(),
+            "Received calculate response"
+        );
+
         check_esri_error(&response_text, "calculate")?;
-        let result: crate::CalculateResult = serde_json::from_str(&response_text)?;
+
+        let result: crate::CalculateResult = serde_json::from_str(&response_text).map_err(|e| {
+            tracing::error!(
+                error = %e,
+                response_preview = %&response_text[..response_text.len().min(500)],
+                "Failed to deserialize CalculateResult"
+            );
+            e
+        })?;
 
         tracing::info!(
             success = result.success(),
             updated_count = ?result.updated_feature_count(),
+            edit_moment = ?result.edit_moment(),
             "Calculate completed"
         );