feat: Add AppSignal APM for performance monitoring and error tracking

- Add appsignal and opentelemetry-instrumentation-starlette dependencies
- Create __appsignal__.py config (reads APPSIGNAL_PUSH_API_KEY from env)
- Instrument Gradio's Starlette app with StarletteInstrumentor for HTTP tracing
- Add custom OpenTelemetry spans to all 4 MCP tool functions in app.py
- Add custom spans to search, indexing, and embedding methods in ai_indexer.py
- Add send_error() reporting in all exception handlers across both files

__appsignal__.py

@@ -0,0 +1,9 @@
+from appsignal import Appsignal
+
+appsignal = Appsignal(
+    active=True,
+    name="MediaSearchMCP",
+    push_api_key="<from-env>",  # APPSIGNAL_PUSH_API_KEY env var overrides this
+    environment="production",    # APPSIGNAL_APP_ENV env var overrides this
+    enable_host_metrics=True,
+)

ai_indexer.py

@@ -16,9 +16,12 @@ import os
 from pathlib import Path
 from typing import List, Dict, Optional
 import logging
+from opentelemetry import trace
+from appsignal import send_error
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
+tracer = trace.get_tracer(__name__)
 
 class LocalMediaIndexer:
     """
@@ -61,6 +64,7 @@ class LocalMediaIndexer:
             self.processor = AutoProcessor.from_pretrained(model_name)
             logger.info("[OK] Model loaded successfully")
         except Exception as e:
+            send_error(e)
             logger.error(f"[ERROR] Error loading model: {e}")
             raise
 
@@ -105,6 +109,7 @@ class LocalMediaIndexer:
             return frames
 
         except Exception as e:
+            send_error(e)
             logger.error(f"[ERROR] Error extracting frames from {video_path}: {e}")
             return []
 
@@ -118,16 +123,18 @@ class LocalMediaIndexer:
         Returns:
             Numpy array embedding or None if error
         """
-        try:
-            inputs = self.processor(images=image, return_tensors="pt").to(self.device)
-            with torch.no_grad():
-                image_features = self.model.get_image_features(**inputs)
-            # Normalize embeddings for cosine similarity
-            image_features = image_features / image_features.norm(dim=-1, keepdim=True)
-            return image_features.cpu().numpy().flatten()
-        except Exception as e:
-            logger.error(f"[ERROR] Error getting embedding: {e}")
-            return None
+        with tracer.start_as_current_span("get_image_embedding") as span:
+            try:
+                inputs = self.processor(images=image, return_tensors="pt").to(self.device)
+                with torch.no_grad():
+                    image_features = self.model.get_image_features(**inputs)
+                # Normalize embeddings for cosine similarity
+                image_features = image_features / image_features.norm(dim=-1, keepdim=True)
+                return image_features.cpu().numpy().flatten()
+            except Exception as e:
+                send_error(e)
+                logger.error(f"[ERROR] Error getting embedding: {e}")
+                return None
 
     def index_local_directory(self, force_reindex: bool = False):
         """
@@ -136,105 +143,115 @@ class LocalMediaIndexer:
         Args:
             force_reindex: If True, rebuild index even if it exists
         """
-        index_path = os.path.join(self.index_dir, "media_index.faiss")
-        paths_path = os.path.join(self.index_dir, "file_paths.json")
-        metadata_path = os.path.join(self.index_dir, "file_metadata.json")
-
-        # Try to load existing index
-        if not force_reindex and os.path.exists(index_path):
-            logger.info("📂 Loading existing index...")
-            if self.load_index():
-                logger.info(f"[OK] Loaded index with {len(self.file_paths)} files")
-                return
+        with tracer.start_as_current_span("index_local_directory") as span:
+            span.set_attribute("index.force_reindex", force_reindex)
+            span.set_attribute("index.media_dir", self.media_dir)
 
-        logger.info(f"🔨 Building new index from: {self.media_dir}")
-        embeddings = []
-        self.file_paths = []
-        self.file_metadata = {}
+            index_path = os.path.join(self.index_dir, "media_index.faiss")
+            paths_path = os.path.join(self.index_dir, "file_paths.json")
+            metadata_path = os.path.join(self.index_dir, "file_metadata.json")
 
-        # Supported file extensions
-        image_exts = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
-        video_exts = {'.mp4', '.mov', '.avi', '.mkv', '.wmv', '.flv'}
-
-        # Walk through local directory
-        file_count = 0
-        for root, dirs, files in os.walk(self.media_dir):
-            for file in sorted(files):
-                file_path = os.path.join(root, file)
-                ext = Path(file).suffix.lower()
-
-                # Get file stats
-                try:
-                    stat = os.stat(file_path)
-                    file_size = stat.st_size
-                except Exception as e:
-                    logger.warning(f"[WARNING] Cannot access {file}: {e}")
-                    continue
-
-                try:
-                    if ext in image_exts:
-                        # Process image
-                        logger.info(f"📸 Processing image: {file}")
-                        image = Image.open(file_path).convert('RGB')
-                        embedding = self.get_image_embedding(image)
-
-                        if embedding is not None:
-                            embeddings.append(embedding)
-                            self.file_paths.append(file_path)
-                            self.file_metadata[file_path] = {
-                                'type': 'image',
-                                'size': file_size,
-                                'name': file
-                            }
-                            file_count += 1
-                            logger.info(f"  [OK] Indexed image: {file}")
-
-                    elif ext in video_exts:
-                        # Process video frames
-                        logger.info(f"🎬 Processing video: {file}")
-                        frames = self.extract_video_frames(file_path)
-
-                        if frames:
-                            # Use average of frame embeddings
-                            frame_embeddings = []
-                            for frame in frames:
-                                emb = self.get_image_embedding(frame)
-                                if emb is not None:
-                                    frame_embeddings.append(emb)
-
-                            if frame_embeddings:
-                                avg_embedding = np.mean(frame_embeddings, axis=0)
-                                embeddings.append(avg_embedding)
+            # Try to load existing index
+            if not force_reindex and os.path.exists(index_path):
+                logger.info("📂 Loading existing index...")
+                if self.load_index():
+                    logger.info(f"[OK] Loaded index with {len(self.file_paths)} files")
+                    span.set_attribute("index.loaded_from_cache", True)
+                    span.set_attribute("index.file_count", len(self.file_paths))
+                    return
+
+            logger.info(f"🔨 Building new index from: {self.media_dir}")
+            embeddings = []
+            self.file_paths = []
+            self.file_metadata = {}
+
+            # Supported file extensions
+            image_exts = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
+            video_exts = {'.mp4', '.mov', '.avi', '.mkv', '.wmv', '.flv'}
+
+            # Walk through local directory
+            file_count = 0
+            for root, dirs, files in os.walk(self.media_dir):
+                for file in sorted(files):
+                    file_path = os.path.join(root, file)
+                    ext = Path(file).suffix.lower()
+
+                    # Get file stats
+                    try:
+                        stat = os.stat(file_path)
+                        file_size = stat.st_size
+                    except Exception as e:
+                        logger.warning(f"[WARNING] Cannot access {file}: {e}")
+                        continue
+
+                    try:
+                        if ext in image_exts:
+                            # Process image
+                            logger.info(f"📸 Processing image: {file}")
+                            image = Image.open(file_path).convert('RGB')
+                            embedding = self.get_image_embedding(image)
+
+                            if embedding is not None:
+                                embeddings.append(embedding)
                                 self.file_paths.append(file_path)
                                 self.file_metadata[file_path] = {
-                                    'type': 'video',
+                                    'type': 'image',
                                     'size': file_size,
-                                    'name': file,
-                                    'frames_indexed': len(frames)
+                                    'name': file
                                 }
                                 file_count += 1
-                                logger.info(f"  [OK] Indexed video: {file}")
-
-                except Exception as e:
-                    logger.error(f"[ERROR] Error processing {file}: {e}")
-
-        if not embeddings:
-            logger.warning("[WARNING] No media files found to index!")
-            logger.warning(f"    Check that {self.media_dir} contains images or videos")
-            return
+                                logger.info(f"  [OK] Indexed image: {file}")
+
+                        elif ext in video_exts:
+                            # Process video frames
+                            logger.info(f"🎬 Processing video: {file}")
+                            frames = self.extract_video_frames(file_path)
+
+                            if frames:
+                                # Use average of frame embeddings
+                                frame_embeddings = []
+                                for frame in frames:
+                                    emb = self.get_image_embedding(frame)
+                                    if emb is not None:
+                                        frame_embeddings.append(emb)
+
+                                if frame_embeddings:
+                                    avg_embedding = np.mean(frame_embeddings, axis=0)
+                                    embeddings.append(avg_embedding)
+                                    self.file_paths.append(file_path)
+                                    self.file_metadata[file_path] = {
+                                        'type': 'video',
+                                        'size': file_size,
+                                        'name': file,
+                                        'frames_indexed': len(frames)
+                                    }
+                                    file_count += 1
+                                    logger.info(f"  [OK] Indexed video: {file}")
+
+                    except Exception as e:
+                        send_error(e)
+                        logger.error(f"[ERROR] Error processing {file}: {e}")
+
+            if not embeddings:
+                logger.warning("[WARNING] No media files found to index!")
+                logger.warning(f"    Check that {self.media_dir} contains images or videos")
+                span.set_attribute("index.file_count", 0)
+                return
 
-        # Create FAISS index
-        logger.info("🔨 Building FAISS index...")
-        embeddings_array = np.array(embeddings).astype('float32')
-        dimension = embeddings_array.shape[1]
+            # Create FAISS index
+            logger.info("🔨 Building FAISS index...")
+            embeddings_array = np.array(embeddings).astype('float32')
+            dimension = embeddings_array.shape[1]
 
-        # Use IndexFlatIP for cosine similarity (embeddings already normalized)
-        self.index = faiss.IndexFlatIP(dimension)
-        self.index.add(embeddings_array)
+            # Use IndexFlatIP for cosine similarity (embeddings already normalized)
+            self.index = faiss.IndexFlatIP(dimension)
+            self.index.add(embeddings_array)
 
-        # Save index locally
-        self.save_index()
-        logger.info(f"[OK] Successfully indexed {len(self.file_paths)} files")
+            # Save index locally
+            self.save_index()
+            span.set_attribute("index.loaded_from_cache", False)
+            span.set_attribute("index.file_count", len(self.file_paths))
+            logger.info(f"[OK] Successfully indexed {len(self.file_paths)} files")
 
     def search(self, query: str, top_k: int = 5) -> List[Dict]:
         """
@@ -247,46 +264,52 @@ class LocalMediaIndexer:
         Returns:
             List of results with file paths and similarity scores
         """
-        if self.index is None:
-            logger.error("[ERROR] Index not loaded! Run index_local_directory() first")
-            return []
+        with tracer.start_as_current_span("indexer_search") as span:
+            span.set_attribute("search.query", query)
+            span.set_attribute("search.top_k", top_k)
 
-        try:
-            logger.info(f"🔍 Searching for: '{query}'")
-
-            # Get query embedding (computed locally)
-            inputs = self.processor(text=[query], return_tensors="pt").to(self.device)
-            with torch.no_grad():
-                text_features = self.model.get_text_features(**inputs)
-
-            # Normalize for cosine similarity
-            text_features = text_features / text_features.norm(dim=-1, keepdim=True)
-            query_embedding = text_features.cpu().numpy().astype('float32')
-
-            # Search locally
-            top_k = min(top_k, len(self.file_paths))
-            scores, indices = self.index.search(query_embedding, top_k)
-
-            results = []
-            for score, idx in zip(scores[0], indices[0]):
-                if idx < len(self.file_paths):
-                    file_path = self.file_paths[idx]
-                    metadata = self.file_metadata.get(file_path, {})
-
-                    results.append({
-                        'file_path': file_path,
-                        'file_name': os.path.basename(file_path),
-                        'similarity_score': float(score),
-                        'media_type': metadata.get('type', 'unknown'),
-                        'file_size_mb': round(metadata.get('size', 0) / (1024*1024), 2)
-                    })
-
-            logger.info(f"  [OK] Found {len(results)} results")
-            return results
+            if self.index is None:
+                logger.error("[ERROR] Index not loaded! Run index_local_directory() first")
+                return []
 
-        except Exception as e:
-            logger.error(f"[ERROR] Search error: {e}")
-            return []
+            try:
+                logger.info(f"🔍 Searching for: '{query}'")
+
+                # Get query embedding (computed locally)
+                inputs = self.processor(text=[query], return_tensors="pt").to(self.device)
+                with torch.no_grad():
+                    text_features = self.model.get_text_features(**inputs)
+
+                # Normalize for cosine similarity
+                text_features = text_features / text_features.norm(dim=-1, keepdim=True)
+                query_embedding = text_features.cpu().numpy().astype('float32')
+
+                # Search locally
+                top_k = min(top_k, len(self.file_paths))
+                scores, indices = self.index.search(query_embedding, top_k)
+
+                results = []
+                for score, idx in zip(scores[0], indices[0]):
+                    if idx < len(self.file_paths):
+                        file_path = self.file_paths[idx]
+                        metadata = self.file_metadata.get(file_path, {})
+
+                        results.append({
+                            'file_path': file_path,
+                            'file_name': os.path.basename(file_path),
+                            'similarity_score': float(score),
+                            'media_type': metadata.get('type', 'unknown'),
+                            'file_size_mb': round(metadata.get('size', 0) / (1024*1024), 2)
+                        })
+
+                span.set_attribute("search.result_count", len(results))
+                logger.info(f"  [OK] Found {len(results)} results")
+                return results
+
+            except Exception as e:
+                send_error(e)
+                logger.error(f"[ERROR] Search error: {e}")
+                return []
 
     def save_index(self):
         """Save index to local disk"""
@@ -306,6 +329,7 @@ class LocalMediaIndexer:
             logger.info(f"💾 Index saved to {self.index_dir}")
 
         except Exception as e:
+            send_error(e)
             logger.error(f"[ERROR] Error saving index: {e}")
 
     def load_index(self) -> bool:
@@ -330,5 +354,6 @@ class LocalMediaIndexer:
             return False
 
         except Exception as e:
+            send_error(e)
             logger.error(f"[ERROR] Error loading index: {e}")
             return False

app.py

@@ -21,6 +21,16 @@ from ai_indexer import LocalMediaIndexer
 import logging
 from huggingface_hub import snapshot_download
 
+# --- AppSignal APM ---
+import appsignal
+from appsignal import set_category, send_error
+from opentelemetry.instrumentation.starlette import StarletteInstrumentor
+from opentelemetry import trace
+
+appsignal.start()
+
+tracer = trace.get_tracer(__name__)
+
 # Load environment variables
 load_dotenv()
 
@@ -61,6 +71,7 @@ if IS_HUGGINGFACE_SPACE or not os.path.exists(MEDIA_DIR) or not os.listdir(MEDIA
         )
         logger.info("Media files downloaded successfully")
     except Exception as e:
+        send_error(e)
         logger.error(f"Failed to download media files: {e}")
         logger.warning("Continuing without demo media files")
 
@@ -77,6 +88,7 @@ try:
     indexer.index_local_directory(force_reindex=False)
 
 except Exception as e:
+    send_error(e)
     logger.error(f"❌ Failed to initialize indexer: {e}")
     raise
 
@@ -98,33 +110,40 @@ def semantic_search(query: str, media_type: str = "all", top_k: int = 5) -> str:
     Returns:
         JSON with ranked search results and similarity scores
     """
-    try:
-        if not query or not query.strip():
-            return json.dumps({"error": "Query cannot be empty"}, indent=2)
-
-        top_k = max(1, min(20, int(top_k)))
-
-        # Perform semantic search (locally)
-        logger.info(f"Searching for: '{query}'")
-        results = indexer.search(query, top_k=top_k)
-
-        # Filter by media type
-        if media_type != "all":
-            results = [r for r in results if r.get('media_type') == media_type]
-
-        response = {
-            "query": query,
-            "media_type": media_type,
-            "count": len(results),
-            "results": results,
-            "note": "All processing done locally on your machine"
-        }
-
-        return json.dumps(response, indent=2)
-
-    except Exception as e:
-        logger.error(f"[ERROR] Search error: {e}")
-        return json.dumps({"error": str(e)}, indent=2)
+    with tracer.start_as_current_span("semantic_search") as span:
+        set_category("mcp_tool.semantic_search")
+        span.set_attribute("search.query", query or "")
+        span.set_attribute("search.media_type", media_type)
+        span.set_attribute("search.top_k", top_k)
+        try:
+            if not query or not query.strip():
+                return json.dumps({"error": "Query cannot be empty"}, indent=2)
+
+            top_k = max(1, min(20, int(top_k)))
+
+            # Perform semantic search (locally)
+            logger.info(f"Searching for: '{query}'")
+            results = indexer.search(query, top_k=top_k)
+
+            # Filter by media type
+            if media_type != "all":
+                results = [r for r in results if r.get('media_type') == media_type]
+
+            response = {
+                "query": query,
+                "media_type": media_type,
+                "count": len(results),
+                "results": results,
+                "note": "All processing done locally on your machine"
+            }
+
+            span.set_attribute("search.result_count", len(results))
+            return json.dumps(response, indent=2)
+
+        except Exception as e:
+            send_error(e)
+            logger.error(f"[ERROR] Search error: {e}")
+            return json.dumps({"error": str(e)}, indent=2)
 
 def get_media_details(file_path: str) -> str:
     """
@@ -136,33 +155,38 @@ def get_media_details(file_path: str) -> str:
     Returns:
         JSON with file details and metadata
     """
-    try:
-        if not os.path.exists(file_path):
-            return json.dumps({"error": f"File not found: {file_path}"}, indent=2)
-
-        stat = os.stat(file_path)
-        ext = Path(file_path).suffix.lower()
-
-        image_exts = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
-        video_exts = {'.mp4', '.mov', '.avi', '.mkv', '.wmv', '.flv'}
-
-        media_type = "image" if ext in image_exts else "video" if ext in video_exts else "unknown"
-
-        details = {
-            "file_path": file_path,
-            "file_name": os.path.basename(file_path),
-            "media_type": media_type,
-            "file_size_mb": round(stat.st_size / (1024*1024), 2),
-            "extension": ext,
-            "exists": True,
-            "in_index": file_path in indexer.file_paths
-        }
-
-        return json.dumps(details, indent=2)
-
-    except Exception as e:
-        logger.error(f"[ERROR] Error getting details: {e}")
-        return json.dumps({"error": str(e)}, indent=2)
+    with tracer.start_as_current_span("get_media_details") as span:
+        set_category("mcp_tool.get_media_details")
+        span.set_attribute("media.file_path", file_path or "")
+        try:
+            if not os.path.exists(file_path):
+                return json.dumps({"error": f"File not found: {file_path}"}, indent=2)
+
+            stat = os.stat(file_path)
+            ext = Path(file_path).suffix.lower()
+
+            image_exts = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
+            video_exts = {'.mp4', '.mov', '.avi', '.mkv', '.wmv', '.flv'}
+
+            media_type = "image" if ext in image_exts else "video" if ext in video_exts else "unknown"
+
+            details = {
+                "file_path": file_path,
+                "file_name": os.path.basename(file_path),
+                "media_type": media_type,
+                "file_size_mb": round(stat.st_size / (1024*1024), 2),
+                "extension": ext,
+                "exists": True,
+                "in_index": file_path in indexer.file_paths
+            }
+
+            span.set_attribute("media.type", media_type)
+            return json.dumps(details, indent=2)
+
+        except Exception as e:
+            send_error(e)
+            logger.error(f"[ERROR] Error getting details: {e}")
+            return json.dumps({"error": str(e)}, indent=2)
 
 def reindex_media(force: bool = False) -> str:
     """
@@ -175,22 +199,27 @@ def reindex_media(force: bool = False) -> str:
     Returns:
         Status message
     """
-    try:
-        logger.info("Starting reindex...")
-        indexer.index_local_directory(force_reindex=force)
-
-        response = {
-            "status": "success",
-            "message": f"Reindexed {len(indexer.file_paths)} files",
-            "media_directory": MEDIA_DIR,
-            "index_directory": INDEX_DIR
-        }
-
-        return json.dumps(response, indent=2)
-
-    except Exception as e:
-        logger.error(f"[ERROR] Reindex error: {e}")
-        return json.dumps({"error": str(e)}, indent=2)
+    with tracer.start_as_current_span("reindex_media") as span:
+        set_category("mcp_tool.reindex_media")
+        span.set_attribute("reindex.force", force)
+        try:
+            logger.info("Starting reindex...")
+            indexer.index_local_directory(force_reindex=force)
+
+            response = {
+                "status": "success",
+                "message": f"Reindexed {len(indexer.file_paths)} files",
+                "media_directory": MEDIA_DIR,
+                "index_directory": INDEX_DIR
+            }
+
+            span.set_attribute("reindex.file_count", len(indexer.file_paths))
+            return json.dumps(response, indent=2)
+
+        except Exception as e:
+            send_error(e)
+            logger.error(f"[ERROR] Reindex error: {e}")
+            return json.dumps({"error": str(e)}, indent=2)
 
 def get_index_stats() -> str:
     """
@@ -199,32 +228,38 @@ def get_index_stats() -> str:
     Returns:
         JSON with index statistics
     """
-    try:
-        image_count = sum(1 for fp in indexer.file_paths
-                         if indexer.file_metadata.get(fp, {}).get('type') == 'image')
-        video_count = sum(1 for fp in indexer.file_paths
-                         if indexer.file_metadata.get(fp, {}).get('type') == 'video')
-
-        total_size = sum(meta.get('size', 0)
-                        for meta in indexer.file_metadata.values())
-
-        stats = {
-            "total_files": len(indexer.file_paths),
-            "images": image_count,
-            "videos": video_count,
-            "total_size_mb": round(total_size / (1024*1024), 2),
-            "media_directory": MEDIA_DIR,
-            "index_directory": INDEX_DIR,
-            "model_device": indexer.device,
-            "model_used": "google/siglip-base-patch16-224",
-            "privacy_note": "All data processed locally - nothing sent to cloud"
-        }
-
-        return json.dumps(stats, indent=2)
-
-    except Exception as e:
-        logger.error(f"[ERROR] Error getting stats: {e}")
-        return json.dumps({"error": str(e)}, indent=2)
+    with tracer.start_as_current_span("get_index_stats") as span:
+        set_category("mcp_tool.get_index_stats")
+        try:
+            image_count = sum(1 for fp in indexer.file_paths
+                             if indexer.file_metadata.get(fp, {}).get('type') == 'image')
+            video_count = sum(1 for fp in indexer.file_paths
+                             if indexer.file_metadata.get(fp, {}).get('type') == 'video')
+
+            total_size = sum(meta.get('size', 0)
+                            for meta in indexer.file_metadata.values())
+
+            stats = {
+                "total_files": len(indexer.file_paths),
+                "images": image_count,
+                "videos": video_count,
+                "total_size_mb": round(total_size / (1024*1024), 2),
+                "media_directory": MEDIA_DIR,
+                "index_directory": INDEX_DIR,
+                "model_device": indexer.device,
+                "model_used": "google/siglip-base-patch16-224",
+                "privacy_note": "All data processed locally - nothing sent to cloud"
+            }
+
+            span.set_attribute("stats.total_files", len(indexer.file_paths))
+            span.set_attribute("stats.images", image_count)
+            span.set_attribute("stats.videos", video_count)
+            return json.dumps(stats, indent=2)
+
+        except Exception as e:
+            send_error(e)
+            logger.error(f"[ERROR] Error getting stats: {e}")
+            return json.dumps({"error": str(e)}, indent=2)
 
 # ============================================================================
 # UI Helper Functions
@@ -671,4 +706,7 @@ if __name__ == "__main__":
         launch_kwargs["server_port"] = 7860
         launch_kwargs["share"] = False
     
+    # Instrument Gradio's internal Starlette/FastAPI app (per AppSignal docs)
+    StarletteInstrumentor().instrument_app(demo.app)
+
     demo.launch(**launch_kwargs)

requirements.txt

@@ -8,3 +8,5 @@ faiss-cpu>=1.7.4
 python-dotenv>=1.0.0
 sentencepiece>=0.2.0
 huggingface_hub>=0.20.0
+appsignal
+opentelemetry-instrumentation-starlette