kinemotion 0.50.0__tar.gz → 0.51.0__tar.gz

{kinemotion-0.50.0 → kinemotion-0.51.0}/.github/workflows/deploy-backend.yml

@@ -7,12 +7,20 @@ on:
       - 'backend/**'
       - 'src/kinemotion/**'
       - '.github/workflows/deploy-backend.yml'
-  workflow_dispatch:
-    inputs:
-      reason:
-        description: 'Reason for manual deployment'
-        required: false
-        type: string
+      - '!frontend/**'
+      - '!docs/**'
+      - '!*.md' # ignore markdown files
+      - '!scripts/**'
+      - '!tests/**'
+      - '!.serena/**'
+      - '!.basic-memory/**'
+      - '!.cursor/**'
+      - '!.vscode/**'
+      - '!.gitignore'
+
+concurrency:
+  group: release-all
+  cancel-in-progress: false
 
 env:
   GCP_PROJECT_ID: kinemotion-backend
@@ -68,9 +76,62 @@ jobs:
           cd backend
           uv run ruff check .
 
+  release:
+    name: Create Release
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ steps.get_version.outputs.version }}
+      released: ${{ steps.get_version.outputs.released }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install backend dependencies
+        run: |
+          cd backend
+          uv sync
+
+      - name: Create Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+          cd backend
+          uv run semantic-release version
+
+      - name: Determine version and release status
+        id: get_version
+        run: |
+          # Check if semantic-release created a new release (tagged commit)
+          if git describe --exact-match --tags HEAD 2>/dev/null; then
+            # Semantic release was created - use version from pyproject.toml
+            VERSION=$(grep '^version = ' backend/pyproject.toml | cut -d'"' -f2)
+            RELEASED="true"
+          else
+            # No semantic release - use fallback version (dev-{short_sha})
+            SHORT_SHA=$(git rev-parse --short HEAD)
+            VERSION="dev-${SHORT_SHA}"
+            RELEASED="false"
+          fi
+
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "released=${RELEASED}" >> $GITHUB_OUTPUT
+          echo "Version: ${VERSION} (released: ${RELEASED})"
+
   build:
     name: Build and Push Docker Image to GCR
-    needs: test
+    needs: release
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -99,7 +160,7 @@ jobs:
           context: .
           file: ./backend/Dockerfile
           push: true
-          tags: ${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:${{ github.sha }},${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:latest
+          tags: ${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:${{ needs.release.outputs.version }},${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:${{ github.sha }},${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:latest
           cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:buildcache
           cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ env.GCP_PROJECT_ID }}/${{ env.SERVICE_NAME }}:buildcache,mode=max
 

{kinemotion-0.50.0 → kinemotion-0.51.0}/.github/workflows/release.yml

@@ -8,6 +8,20 @@ on:
       - '.github/workflows/deploy-backend.yml'
       - 'backend/**'
       - 'frontend/**'
+      - '*.md' # ignore markdown files
+      - 'scripts/**'
+      - '.serena/**'
+      - '.basic-memory/**'
+      - '.cursor/**'
+      - '.vscode/**'
+      - '.gitignore'
+      - '.claude/**'
+      - '.gemini/**'
+      - '.mcp/**'
+
+concurrency:
+  group: release-all
+  cancel-in-progress: false
 
 jobs:
   test:

{kinemotion-0.50.0 → kinemotion-0.51.0}/.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
         additional_dependencies:
           - mdformat-gfm>=0.3.5  # GitHub Flavored Markdown
           - mdformat-tables  # Table formatting
-        exclude: (^CLAUDE\.md$|^CHANGELOG\.md$|^presentation/revealjs/slides\.md$|\.claude/agents/.*\.md$|\.basic-memory/.*\.md$|\.serena/.*\.md$)
+        exclude: (^CLAUDE\.md$|^CHANGELOG\.md$|^backend/CHANGELOG\.md$|^presentation/revealjs/slides\.md$|\.claude/agents/.*\.md$|\.basic-memory/.*\.md$|\.serena/.*\.md$)
 
   - repo: https://github.com/compilerla/conventional-pre-commit
     rev: v4.3.0

{kinemotion-0.50.0 → kinemotion-0.51.0}/CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.51.0 (2025-12-13)
+
+### Bug Fixes
+
+- Correct MetricsData instantiation and metrics_count calculation
+  ([`e2ebca1`](https://github.com/feniix/kinemotion/commit/e2ebca1d5614faa86cdb3c4e23ef9fa034cd8d2a))
+
+- Correct uv.lock path in backend semantic-release build command
+  ([`650c3bc`](https://github.com/feniix/kinemotion/commit/650c3bc7b1a18814f179e7f1e4835000186ee45c))
+
+- Remove invalid search_tag_format and fix tag_format syntax
+  ([`46c2a2a`](https://github.com/feniix/kinemotion/commit/46c2a2af5fa97a833256896253b300c307d3a528))
+
+- Update error handling tests to use 'status' field instead of 'status_code'
+  ([`890e54b`](https://github.com/feniix/kinemotion/commit/890e54b6ac7bead9dceb0f34fdaeb4789e3b3dbd))
+
+- **docs**: Enhance api module docstring with examples and analysis types
+  ([`94e32f1`](https://github.com/feniix/kinemotion/commit/94e32f1061505747c0345e8683a61bcf8dc60ee3))
+
+- **docs**: Improve app.py module docstring with comprehensive feature overview
+  ([`eab977c`](https://github.com/feniix/kinemotion/commit/eab977c237f2318f5dc0b94a32f4b736053bfc00))
+
+- **docs**: Improve module docstrings in src/kinemotion and backend/src/
+  ([`f59d649`](https://github.com/feniix/kinemotion/commit/f59d6494c8735fa3e83f8bdbedefce0b6c405cf5))
+
+### Continuous Integration
+
+- Add semantic-release configuration to backend
+  ([`f8e447c`](https://github.com/feniix/kinemotion/commit/f8e447c86b03d7ad6cf9e40d67217371f642f254))
+
+- Improve workflow configuration and add backend versioning
+  ([`8d86933`](https://github.com/feniix/kinemotion/commit/8d8693398b6aec20c847ae0616488dd3b90c35af))
+
+- Use shared concurrency group to prevent race conditions between CLI and backend release workflows
+  ([`038e744`](https://github.com/feniix/kinemotion/commit/038e744ed13aa52c78557df8257995861de5308e))
+
+### Features
+
+- Add comprehensive granular logging for pipeline stage timing
+  ([`0489222`](https://github.com/feniix/kinemotion/commit/04892221faf2cb39f355867475242b8baafa34cd))
+
+- Implement continuous deployment with optional semantic releases
+  ([`3596e47`](https://github.com/feniix/kinemotion/commit/3596e47e055dd54dda130bba9d7e78c14c4b2819))
+
+### Refactoring
+
+- Decouple semantic-release configs with directory-specific filtering
+  ([`b7d4fef`](https://github.com/feniix/kinemotion/commit/b7d4fefcff2972d2d347dfef69a830b1f2473cfc))
+
+- Namespace semantic-release tags and reset backend to 0.1.0
+  ([`76d9c5b`](https://github.com/feniix/kinemotion/commit/76d9c5b4cedebfd56c5e5ec5272e260620520cd3))
+
+- Restore search_tag_format for decoupled version detection
+  ([`e9f163d`](https://github.com/feniix/kinemotion/commit/e9f163dd85aa81b0dce52d26339bcc858e9b6ef5))
+
+- Separate release job in backend deployment workflow
+  ([`521f03f`](https://github.com/feniix/kinemotion/commit/521f03f4d32c6bcf0b048c2fba3d54d74c7c0677))
+
+
 ## v0.50.0 (2025-12-13)
 
 ### Bug Fixes

{kinemotion-0.50.0 → kinemotion-0.51.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.50.0
+Version: 0.51.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

kinemotion-0.51.0/backend/CHANGELOG.md

@@ -0,0 +1,58 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v0.1.1 (2025-12-13)
+
+### Bug Fixes
+
+- **docs**: Enhance api module docstring with examples and analysis types
+  ([`94e32f1`](https://github.com/feniix/kinemotion/commit/94e32f1061505747c0345e8683a61bcf8dc60ee3))
+
+
+## v0.1.0 (2025-12-13)
+
+- Initial Release
+
+## v0.1.0 (2025-12-13)
+
+- Initial Release
+
+## v0.52.0 (2025-12-13)
+
+### Features
+
+- Implement continuous deployment with optional semantic releases
+  ([`3596e47`](https://github.com/feniix/kinemotion/commit/3596e47e055dd54dda130bba9d7e78c14c4b2819))
+
+### Refactoring
+
+- Decouple semantic-release configs with directory-specific filtering
+  ([`b7d4fef`](https://github.com/feniix/kinemotion/commit/b7d4fefcff2972d2d347dfef69a830b1f2473cfc))
+
+- Separate release job in backend deployment workflow
+  ([`521f03f`](https://github.com/feniix/kinemotion/commit/521f03f4d32c6bcf0b048c2fba3d54d74c7c0677))
+
+
+## v0.51.0 (2025-12-13)
+
+### Bug Fixes
+
+- Correct MetricsData instantiation and metrics_count calculation
+  ([`e2ebca1`](https://github.com/feniix/kinemotion/commit/e2ebca1d5614faa86cdb3c4e23ef9fa034cd8d2a))
+
+- Update error handling tests to use status field instead of status_code
+  ([`890e54b`](https://github.com/feniix/kinemotion/commit/890e54b6ac7bead9dceb0f34fdaeb4789e3b3dbd))
+
+### Continuous Integration
+
+- Add semantic-release configuration to backend
+  ([`f8e447c`](https://github.com/feniix/kinemotion/commit/f8e447c86b03d7ad6cf9e40d67217371f642f254))
+
+- Improve workflow configuration and add backend versioning
+  ([`8d86933`](https://github.com/feniix/kinemotion/commit/8d8693398b6aec20c847ae0616488dd3b90c35af))
+
+### Features
+
+- Add comprehensive granular logging for pipeline stage timing
+  ([`0489222`](https://github.com/feniix/kinemotion/commit/04892221faf2cb39f355867475242b8baafa34cd))

{kinemotion-0.50.0 → kinemotion-0.51.0}/backend/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion-backend"
-version = "0.1.0"
+version = "0.1.1"
 description = "FastAPI backend for Kinemotion video analysis"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
@@ -59,6 +59,7 @@ dev = [
     "httpx>=0.26.0",
     "ruff>=0.1.8",
     "pyright>=1.1.380",
+    "python-semantic-release>=9.8.2",
 ]
 
 [tool.pytest.ini_options]
@@ -153,3 +154,32 @@ reportUnusedClass = "warning"
 reportUnusedFunction = "warning"
 reportUnusedVariable = "warning"
 reportDuplicateImport = "warning"
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+changelog_file = "CHANGELOG.md"
+tag_format = "kinemotion-backend-v{version}"
+build_command = """\
+    uv lock --upgrade-package "$PACKAGE_NAME"
+    git add ../uv.lock
+    uv build
+"""
+dist_path = "dist/"
+upload_to_vcs_release = true
+remove_dist = false
+patch_without_tag = false
+major_on_zero = false
+allow_zero_version = true
+commit_message = "chore(release): {version} [skip ci]"
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "chore", "build", "ci"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+
+[tool.semantic_release.publish]
+# Only process commits affecting backend/src/kinemotion_backend/ for backend releases
+# Tests (backend/tests/) are excluded since they are not part of the public API
+# This decouples backend versioning from root CLI versioning
+directories = ["backend/src/kinemotion_backend"]

{kinemotion-0.50.0 → kinemotion-0.51.0}/backend/src/kinemotion_backend/analysis_api.py

@@ -1,4 +1,22 @@
-"""API endpoints for analysis sessions and coach feedback."""
+"""API endpoints for analysis sessions and coach feedback.
+
+This module provides FastAPI endpoints for managing video analysis sessions and
+coach feedback. Key responsibilities:
+
+- Create and retrieve analysis sessions for uploaded videos
+- Process video analysis requests through the kinemotion engine
+- Store and retrieve coach feedback linked to analysis sessions
+- Handle authentication via Supabase JWT tokens
+- Manage session state and error handling
+
+Endpoints:
+    POST /api/analysis/sessions - Create a new analysis session
+    GET /api/analysis/sessions/{session_id} - Retrieve session details
+    POST /api/analysis/sessions/{session_id}/feedback - Add coach feedback
+    GET /api/analysis/sessions/{session_id}/feedback - Retrieve feedback
+
+All endpoints require JWT authentication via Authorization header.
+"""
 
 from typing import Any
 

{kinemotion-0.50.0 → kinemotion-0.51.0}/backend/src/kinemotion_backend/app.py

@@ -1,6 +1,18 @@
 """FastAPI application for Kinemotion video analysis backend.
 
-Real metrics integration with Cloudflare R2 storage for video and results management.
+This module provides a REST API for analyzing jump mechanics from video files.
+It handles video uploads, processes them through the kinemotion analysis engine
+(drop jump and counter-movement jump analysis), stores results in Supabase, and
+manages video/result artifacts in Cloudflare R2 storage.
+
+Key features:
+- Video upload and processing for multiple jump types
+- Integration with MediaPipe pose tracking
+- Metrics calculation (RSI, flight time, jump height, etc.)
+- Result persistence in Supabase database
+- Artifact management in Cloudflare R2 storage
+- Rate limiting and request logging middleware
+- CORS support for frontend integration
 """
 
 import os

{kinemotion-0.50.0 → kinemotion-0.51.0}/backend/src/kinemotion_backend/routes/analysis.py

@@ -56,6 +56,10 @@ async def analyze_video(
     Raises:
         HTTPException: If validation or processing fails
     """
+    import time
+
+    start_time = time.time()
+
     # Validate referer (prevent direct API access)
     validate_referer(referer, x_test_password)
 
@@ -66,6 +70,14 @@ async def analyze_video(
         # Convert debug string to boolean
         enable_debug = debug.lower() == "true"
 
+        logger.info(
+            "analyze_endpoint_processing",
+            jump_type=jump_type,
+            quality=quality,
+            debug=enable_debug,
+            filename=file.filename,
+        )
+
         # Perform analysis using service layer
         result: AnalysisResponse = await analysis_service.analyze_video(
             file=file,
@@ -75,14 +87,25 @@ async def analyze_video(
             user_id=None,  # TODO: Extract from auth when available
         )
 
+        # Log successful response
+        elapsed = time.time() - start_time
+        logger.info(
+            "analyze_endpoint_success",
+            status_code=result.status,
+            processing_time_s=round(elapsed, 2),
+            has_metrics=result.metrics is not None,
+        )
+
         # Return JSON response
         return JSONResponse(content=result.to_dict())
 
     except ValueError as e:
-        logger.error(
-            "Validation failed",
+        elapsed = time.time() - start_time
+        logger.warning(
+            "analyze_endpoint_validation_error",
             upload_id=request.headers.get("x-upload-id", "unknown"),
             error=str(e),
+            processing_time_s=round(elapsed, 2),
         )
 
         # Return validation error
@@ -94,7 +117,7 @@ async def analyze_video(
             results_url=None,
             debug_video_url=None,
             original_video_url=None,
-            processing_time_s=0.0,
+            processing_time_s=elapsed,
         )
 
         return JSONResponse(
@@ -103,10 +126,13 @@ async def analyze_video(
         )
 
     except Exception as e:
+        elapsed = time.time() - start_time
         logger.error(
-            "Video analysis failed",
+            "analyze_endpoint_error",
             upload_id=request.headers.get("x-upload-id", "unknown"),
             error=str(e),
+            error_type=type(e).__name__,
+            processing_time_s=round(elapsed, 2),
             exc_info=True,
         )
 
@@ -119,7 +145,7 @@ async def analyze_video(
             results_url=None,
             debug_video_url=None,
             original_video_url=None,
-            processing_time_s=0.0,
+            processing_time_s=elapsed,
         )
 
         return JSONResponse(

{kinemotion-0.50.0 → kinemotion-0.51.0}/backend/src/kinemotion_backend/services/analysis_service.py

@@ -1,5 +1,7 @@
+import time
 from pathlib import Path
 
+import structlog
 from fastapi import UploadFile
 
 from ..models.responses import AnalysisResponse, MetricsData
@@ -7,6 +9,8 @@ from .storage_service import StorageService
 from .validation import validate_jump_type, validate_video_file
 from .video_processor import VideoProcessorService
 
+logger = structlog.get_logger(__name__)
+
 
 class AnalysisService:
     """Service for orchestrating video analysis workflow."""
@@ -39,25 +43,43 @@ class AnalysisService:
         Raises:
             ValueError: If validation fails
         """
-        import time
-
         from kinemotion.core.timing import PerformanceTimer
 
         start_time = time.time()
         temp_path: str | None = None
         temp_debug_video_path: str | None = None
 
+        # Log analysis start
+        logger.info(
+            "video_analysis_started",
+            jump_type=jump_type,
+            quality=quality,
+            debug_overlay=debug,
+            file_name=file.filename,
+        )
+
         # Validate inputs (let ValueError propagate to route handler)
+        logger.info("validating_video_file", filename=file.filename)
         validate_video_file(file)
+
+        logger.info("validating_jump_type", jump_type=jump_type)
         normalized_jump_type = validate_jump_type(jump_type)
 
+        logger.info(
+            "validation_complete",
+            normalized_jump_type=normalized_jump_type,
+        )
+
         try:
             # Generate unique storage key
+            logger.info("generating_storage_key", original_filename=file.filename)
             storage_key = await self.storage_service.generate_unique_key(
                 file.filename or "video.mp4", user_id
             )
+            logger.info("storage_key_generated", storage_key=storage_key)
 
             # Save uploaded file to temporary location
+            logger.info("saving_uploaded_file", storage_key=storage_key)
             temp_path = self.storage_service.get_temp_file_path(Path(storage_key).name)
             assert temp_path is not None
 
@@ -68,6 +90,13 @@ class AnalysisService:
                     raise ValueError("File size exceeds maximum of 500MB")
                 temp_file.write(content)
 
+            file_size_mb = len(content) / (1024 * 1024)
+            logger.info(
+                "uploaded_file_saved",
+                temp_path=temp_path,
+                file_size_mb=round(file_size_mb, 2),
+            )
+
             # Create temporary debug video path if debug is enabled
             import tempfile
 
@@ -75,8 +104,12 @@ class AnalysisService:
                 temp_debug = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
                 temp_debug_video_path = temp_debug.name
                 temp_debug.close()
+                logger.info(
+                    "debug_video_path_created", debug_video_path=temp_debug_video_path
+                )
 
-            # Process video
+            # Process video with detailed timing
+            logger.info("video_processing_started")
             timer = PerformanceTimer()
             with timer.measure("video_processing"):
                 metrics = await self.video_processor.process_video_async(
@@ -87,33 +120,71 @@ class AnalysisService:
                     timer=timer,
                 )
 
+            # Log individual pipeline stage timings
+            stage_metrics = timer.get_metrics()
+
+            # Log each timing stage individually (for detailed performance tracking)
+            for stage_name, duration_s in stage_metrics.items():
+                duration_ms = duration_s * 1000
+                logger.info(stage_name, duration_ms=round(duration_ms, 1))
+
+            # Log overall processing completion summary
+            total_duration_s = stage_metrics.get("video_processing", 0)
+            logger.info(
+                "video_processing_completed",
+                total_duration_s=round(total_duration_s, 2),
+                duration_ms=round(total_duration_s * 1000, 1),
+            )
+
             # Upload original video to storage
+            logger.info("uploading_original_video", storage_key=storage_key)
             original_video_url = await self.storage_service.upload_video(
                 temp_path, f"videos/{storage_key}"
             )
+            logger.info("original_video_uploaded", url=original_video_url)
 
-            # Upload analysis results
+            # Upload analysis results with timing
+            logger.info("uploading_analysis_results", storage_key=storage_key)
+            results_start = time.time()
             results_url = await self.storage_service.upload_analysis_results(
                 metrics, f"results/{storage_key}.json"
             )
+            results_duration_ms = (time.time() - results_start) * 1000
+            logger.info(
+                "r2_results_upload",
+                duration_ms=round(results_duration_ms, 1),
+                url=results_url,
+                key=f"results/{storage_key}.json",
+            )
 
             # Upload debug video if it was created
             debug_video_url = None
             if temp_debug_video_path and Path(temp_debug_video_path).exists():
                 if Path(temp_debug_video_path).stat().st_size > 0:
+                    logger.info("uploading_debug_video", storage_key=storage_key)
+                    debug_start = time.time()
                     debug_video_url = await self.storage_service.upload_video(
                         temp_debug_video_path, f"debug_videos/{storage_key}_debug.mp4"
                     )
+                    debug_duration_ms = (time.time() - debug_start) * 1000
+                    logger.info(
+                        "r2_debug_video_upload",
+                        duration_ms=round(debug_duration_ms, 1),
+                        url=debug_video_url,
+                        key=f"debug_videos/{storage_key}_debug.mp4",
+                    )
+                else:
+                    logger.info("debug_video_empty_skipping_upload")
 
             # Calculate processing time
             processing_time = time.time() - start_time
 
-            # Clean up temporary files
-            Path(temp_path).unlink(missing_ok=True)
-            if temp_debug_video_path and Path(temp_debug_video_path).exists():
-                Path(temp_debug_video_path).unlink(missing_ok=True)
+            # Count metrics from the data field
+            metrics_count = len(metrics.get("data", {}))
 
-            return AnalysisResponse(
+            # Log response serialization timing
+            serialization_start = time.time()
+            response_data = AnalysisResponse(
                 status=200,
                 message="Analysis completed successfully",
                 metrics=MetricsData(**metrics),
@@ -123,9 +194,40 @@ class AnalysisService:
                 error=None,
                 processing_time_s=processing_time,
             )
+            serialization_duration_ms = (time.time() - serialization_start) * 1000
+            logger.info(
+                "response_serialization",
+                duration_ms=round(serialization_duration_ms, 1),
+            )
+
+            # Clean up temporary files with timing
+            logger.info("cleaning_up_temporary_files")
+            cleanup_start = time.time()
+            Path(temp_path).unlink(missing_ok=True)
+            if temp_debug_video_path and Path(temp_debug_video_path).exists():
+                Path(temp_debug_video_path).unlink(missing_ok=True)
+            cleanup_duration_ms = (time.time() - cleanup_start) * 1000
+            logger.info(
+                "temp_file_cleanup",
+                duration_ms=round(cleanup_duration_ms, 1),
+            )
+
+            logger.info(
+                "video_analysis_completed",
+                jump_type=normalized_jump_type,
+                duration_ms=round(processing_time * 1000, 1),
+                metrics_count=metrics_count,
+            )
+
+            return response_data
 
-        except ValueError:
+        except ValueError as e:
             # Clean up on validation error and re-raise
+            logger.error(
+                "video_analysis_validation_error",
+                error=str(e),
+                processing_time_s=round(time.time() - start_time, 2),
+            )
             if temp_path is not None:
                 Path(temp_path).unlink(missing_ok=True)
             if temp_debug_video_path and Path(temp_debug_video_path).exists():
@@ -134,12 +236,19 @@ class AnalysisService:
 
         except Exception as e:
             # Clean up on other errors
+            processing_time = time.time() - start_time
+            logger.error(
+                "video_analysis_failed",
+                error=str(e),
+                error_type=type(e).__name__,
+                processing_time_s=round(processing_time, 2),
+                exc_info=True,
+            )
             if temp_path is not None:
                 Path(temp_path).unlink(missing_ok=True)
             if temp_debug_video_path and Path(temp_debug_video_path).exists():
                 Path(temp_debug_video_path).unlink(missing_ok=True)
 
-            processing_time = time.time() - start_time
             return AnalysisResponse(
                 status=500,
                 message=f"Analysis failed: {str(e)}",