Skip to main content

torsh_profiler/
custom_tools.rs

1//! Custom tool APIs for profiler integration
2//!
3//! This module provides extensible APIs for integrating custom profiling tools
4//! and frameworks into the torsh-profiler ecosystem.
5
6use crate::ProfileEvent;
7use anyhow::Result;
8use once_cell::sync::Lazy;
9use parking_lot::Mutex;
10use serde::{Deserialize, Serialize};
11use std::collections::HashMap;
12use std::time::{Instant, SystemTime};
13
14/// Global registry for custom profiling tools
15static CUSTOM_TOOL_REGISTRY: Lazy<Mutex<CustomToolRegistry>> =
16    Lazy::new(|| Mutex::new(CustomToolRegistry::new()));
17
18/// Custom tool integration trait
19pub trait CustomTool: Send + Sync {
20    /// Initialize the custom tool
21    fn initialize(&mut self, config: &ToolConfig) -> Result<()>;
22
23    /// Start profiling session
24    fn start_session(&mut self, session_id: &str) -> Result<()>;
25
26    /// Record a profiling event
27    fn record_event(&mut self, event: &ProfileEvent) -> Result<()>;
28
29    /// Stop profiling session
30    fn stop_session(&mut self, session_id: &str) -> Result<()>;
31
32    /// Export collected data
33    fn export_data(&self, format: &ExportFormat) -> Result<Vec<u8>>;
34
35    /// Get tool statistics
36    fn get_statistics(&self) -> Result<ToolStatistics>;
37
38    /// Cleanup resources
39    fn cleanup(&mut self) -> Result<()>;
40
41    /// Get tool name
42    fn name(&self) -> &str;
43
44    /// Get tool version
45    fn version(&self) -> &str;
46}
47
48/// Configuration for custom tools
49#[derive(Debug, Clone, Serialize, Deserialize)]
50pub struct ToolConfig {
51    pub name: String,
52    pub version: String,
53    pub enabled: bool,
54    pub sampling_rate: f64,
55    pub buffer_size: usize,
56    pub output_path: Option<String>,
57    pub custom_options: HashMap<String, String>,
58}
59
60impl Default for ToolConfig {
61    fn default() -> Self {
62        Self {
63            name: "custom_tool".to_string(),
64            version: "1.0.0".to_string(),
65            enabled: true,
66            sampling_rate: 1.0,
67            buffer_size: 1024,
68            output_path: None,
69            custom_options: HashMap::new(),
70        }
71    }
72}
73
74/// Export format for custom tools
75#[derive(Debug, Clone, Serialize, Deserialize)]
76pub enum ExportFormat {
77    Json,
78    Csv,
79    Binary,
80    Custom(String),
81}
82
83/// Tool statistics
84#[derive(Debug, Clone, Serialize, Deserialize)]
85pub struct ToolStatistics {
86    pub events_recorded: u64,
87    pub sessions_completed: u64,
88    pub total_duration_ns: u64,
89    pub memory_usage_bytes: u64,
90    pub error_count: u64,
91    pub last_updated: SystemTime,
92}
93
94impl Default for ToolStatistics {
95    fn default() -> Self {
96        Self {
97            events_recorded: 0,
98            sessions_completed: 0,
99            total_duration_ns: 0,
100            memory_usage_bytes: 0,
101            error_count: 0,
102            last_updated: SystemTime::now(),
103        }
104    }
105}
106
107/// Registry for managing custom tools
108#[derive(Default)]
109pub struct CustomToolRegistry {
110    tools: HashMap<String, Box<dyn CustomTool>>,
111    configs: HashMap<String, ToolConfig>,
112}
113
114impl CustomToolRegistry {
115    pub fn new() -> Self {
116        Self {
117            tools: HashMap::new(),
118            configs: HashMap::new(),
119        }
120    }
121
122    /// Register a custom tool
123    pub fn register_tool(&mut self, tool: Box<dyn CustomTool>, config: ToolConfig) -> Result<()> {
124        let name = tool.name().to_string();
125        self.configs.insert(name.clone(), config);
126        self.tools.insert(name, tool);
127        Ok(())
128    }
129
130    /// Unregister a custom tool
131    pub fn unregister_tool(&mut self, name: &str) -> Result<()> {
132        if let Some(mut tool) = self.tools.remove(name) {
133            tool.cleanup()?;
134        }
135        self.configs.remove(name);
136        Ok(())
137    }
138
139    /// Get tool by name
140    pub fn get_tool(&mut self, name: &str) -> Option<&mut Box<dyn CustomTool>> {
141        self.tools.get_mut(name)
142    }
143
144    /// Initialize all tools
145    pub fn initialize_all(&mut self) -> Result<()> {
146        for (name, tool) in &mut self.tools {
147            if let Some(config) = self.configs.get(name) {
148                tool.initialize(config)?;
149            }
150        }
151        Ok(())
152    }
153
154    /// Start session on all tools
155    pub fn start_session_all(&mut self, session_id: &str) -> Result<()> {
156        for tool in self.tools.values_mut() {
157            tool.start_session(session_id)?;
158        }
159        Ok(())
160    }
161
162    /// Record event on all tools
163    pub fn record_event_all(&mut self, event: &ProfileEvent) -> Result<()> {
164        for tool in self.tools.values_mut() {
165            tool.record_event(event)?;
166        }
167        Ok(())
168    }
169
170    /// Stop session on all tools
171    pub fn stop_session_all(&mut self, session_id: &str) -> Result<()> {
172        for tool in self.tools.values_mut() {
173            tool.stop_session(session_id)?;
174        }
175        Ok(())
176    }
177
178    /// Get all tool statistics
179    pub fn get_all_statistics(&self) -> HashMap<String, ToolStatistics> {
180        let mut stats = HashMap::new();
181        for (name, tool) in &self.tools {
182            if let Ok(tool_stats) = tool.get_statistics() {
183                stats.insert(name.clone(), tool_stats);
184            }
185        }
186        stats
187    }
188
189    /// List all registered tools
190    pub fn list_tools(&self) -> Vec<String> {
191        self.tools.keys().cloned().collect()
192    }
193}
194
195/// Example custom tool implementation
196pub struct ExampleCustomTool {
197    name: String,
198    version: String,
199    statistics: ToolStatistics,
200    events: Vec<ProfileEvent>,
201    active_sessions: Vec<String>,
202}
203
204impl ExampleCustomTool {
205    pub fn new(name: String, version: String) -> Self {
206        Self {
207            name,
208            version,
209            statistics: ToolStatistics::default(),
210            events: Vec::new(),
211            active_sessions: Vec::new(),
212        }
213    }
214}
215
216impl CustomTool for ExampleCustomTool {
217    fn initialize(&mut self, config: &ToolConfig) -> Result<()> {
218        println!("Initializing custom tool: {}", config.name);
219        Ok(())
220    }
221
222    fn start_session(&mut self, session_id: &str) -> Result<()> {
223        self.active_sessions.push(session_id.to_string());
224        Ok(())
225    }
226
227    fn record_event(&mut self, event: &ProfileEvent) -> Result<()> {
228        self.events.push(event.clone());
229        self.statistics.events_recorded += 1;
230        self.statistics.last_updated = SystemTime::now();
231        Ok(())
232    }
233
234    fn stop_session(&mut self, session_id: &str) -> Result<()> {
235        self.active_sessions.retain(|s| s != session_id);
236        self.statistics.sessions_completed += 1;
237        Ok(())
238    }
239
240    fn export_data(&self, format: &ExportFormat) -> Result<Vec<u8>> {
241        match format {
242            ExportFormat::Json => {
243                let json = serde_json::to_string_pretty(&self.events)?;
244                Ok(json.into_bytes())
245            }
246            ExportFormat::Csv => {
247                let mut csv = String::new();
248                csv.push_str("timestamp,name,duration_ns,thread_id\n");
249                for event in &self.events {
250                    csv.push_str(&format!(
251                        "{},{},{},{}\n",
252                        event.start_us,
253                        event.name,
254                        event.duration_us * 1000, // Convert to ns
255                        event.thread_id as u64
256                    ));
257                }
258                Ok(csv.into_bytes())
259            }
260            _ => Err(anyhow::anyhow!("Unsupported export format")),
261        }
262    }
263
264    fn get_statistics(&self) -> Result<ToolStatistics> {
265        Ok(self.statistics.clone())
266    }
267
268    fn cleanup(&mut self) -> Result<()> {
269        self.events.clear();
270        self.active_sessions.clear();
271        Ok(())
272    }
273
274    fn name(&self) -> &str {
275        &self.name
276    }
277
278    fn version(&self) -> &str {
279        &self.version
280    }
281}
282
283/// External tool bridge for integrating third-party tools
284pub struct ExternalToolBridge {
285    name: String,
286    version: String,
287    command: String,
288    args: Vec<String>,
289    statistics: ToolStatistics,
290}
291
292impl ExternalToolBridge {
293    pub fn new(name: String, version: String, command: String, args: Vec<String>) -> Self {
294        Self {
295            name,
296            version,
297            command,
298            args,
299            statistics: ToolStatistics::default(),
300        }
301    }
302}
303
304impl CustomTool for ExternalToolBridge {
305    fn initialize(&mut self, config: &ToolConfig) -> Result<()> {
306        // Initialize external tool process
307        std::process::Command::new(&self.command)
308            .args(&self.args)
309            .arg("--initialize")
310            .output()?;
311        Ok(())
312    }
313
314    fn start_session(&mut self, session_id: &str) -> Result<()> {
315        std::process::Command::new(&self.command)
316            .args(&self.args)
317            .arg("--start-session")
318            .arg(session_id)
319            .output()?;
320        Ok(())
321    }
322
323    fn record_event(&mut self, event: &ProfileEvent) -> Result<()> {
324        let event_json = serde_json::to_string(event)?;
325        std::process::Command::new(&self.command)
326            .args(&self.args)
327            .arg("--record-event")
328            .arg(&event_json)
329            .output()?;
330        self.statistics.events_recorded += 1;
331        Ok(())
332    }
333
334    fn stop_session(&mut self, session_id: &str) -> Result<()> {
335        std::process::Command::new(&self.command)
336            .args(&self.args)
337            .arg("--stop-session")
338            .arg(session_id)
339            .output()?;
340        self.statistics.sessions_completed += 1;
341        Ok(())
342    }
343
344    fn export_data(&self, format: &ExportFormat) -> Result<Vec<u8>> {
345        let format_str = match format {
346            ExportFormat::Json => "json",
347            ExportFormat::Csv => "csv",
348            ExportFormat::Binary => "binary",
349            ExportFormat::Custom(fmt) => fmt,
350        };
351
352        let output = std::process::Command::new(&self.command)
353            .args(&self.args)
354            .arg("--export")
355            .arg(format_str)
356            .output()?;
357
358        Ok(output.stdout)
359    }
360
361    fn get_statistics(&self) -> Result<ToolStatistics> {
362        Ok(self.statistics.clone())
363    }
364
365    fn cleanup(&mut self) -> Result<()> {
366        std::process::Command::new(&self.command)
367            .args(&self.args)
368            .arg("--cleanup")
369            .output()?;
370        Ok(())
371    }
372
373    fn name(&self) -> &str {
374        &self.name
375    }
376
377    fn version(&self) -> &str {
378        &self.version
379    }
380}
381
382/// Public API functions for custom tool integration
383/// Register a custom tool with the global registry
384pub fn register_custom_tool(tool: Box<dyn CustomTool>, config: ToolConfig) -> Result<()> {
385    CUSTOM_TOOL_REGISTRY.lock().register_tool(tool, config)
386}
387
388/// Unregister a custom tool from the global registry
389pub fn unregister_custom_tool(name: &str) -> Result<()> {
390    CUSTOM_TOOL_REGISTRY.lock().unregister_tool(name)
391}
392
393/// Initialize all registered custom tools
394pub fn initialize_custom_tools() -> Result<()> {
395    CUSTOM_TOOL_REGISTRY.lock().initialize_all()
396}
397
398/// Start profiling session on all custom tools
399pub fn start_custom_tool_session(session_id: &str) -> Result<()> {
400    CUSTOM_TOOL_REGISTRY.lock().start_session_all(session_id)
401}
402
403/// Record event on all custom tools
404pub fn record_custom_tool_event(event: &ProfileEvent) -> Result<()> {
405    CUSTOM_TOOL_REGISTRY.lock().record_event_all(event)
406}
407
408/// Stop profiling session on all custom tools
409pub fn stop_custom_tool_session(session_id: &str) -> Result<()> {
410    CUSTOM_TOOL_REGISTRY.lock().stop_session_all(session_id)
411}
412
413/// Get statistics from all custom tools
414pub fn get_custom_tool_statistics() -> HashMap<String, ToolStatistics> {
415    CUSTOM_TOOL_REGISTRY.lock().get_all_statistics()
416}
417
418/// List all registered custom tools
419pub fn list_custom_tools() -> Vec<String> {
420    CUSTOM_TOOL_REGISTRY.lock().list_tools()
421}
422
423/// Create an example custom tool
424pub fn create_example_tool(name: String, version: String) -> Box<dyn CustomTool> {
425    Box::new(ExampleCustomTool::new(name, version))
426}
427
428/// Create an external tool bridge
429pub fn create_external_tool_bridge(
430    name: String,
431    version: String,
432    command: String,
433    args: Vec<String>,
434) -> Box<dyn CustomTool> {
435    Box::new(ExternalToolBridge::new(name, version, command, args))
436}
437
438#[cfg(test)]
439mod tests {
440    use super::*;
441    use std::time::SystemTime;
442
443    #[test]
444    fn test_custom_tool_registration() {
445        let mut registry = CustomToolRegistry::new();
446        let tool = create_example_tool("test_tool".to_string(), "1.0.0".to_string());
447        let config = ToolConfig::default();
448
449        assert!(registry.register_tool(tool, config).is_ok());
450        assert_eq!(registry.list_tools(), vec!["test_tool"]);
451    }
452
453    #[test]
454    fn test_tool_lifecycle() {
455        let mut registry = CustomToolRegistry::new();
456        let tool = create_example_tool("test_tool".to_string(), "1.0.0".to_string());
457        let config = ToolConfig::default();
458
459        registry.register_tool(tool, config).unwrap();
460        registry.initialize_all().unwrap();
461        registry.start_session_all("test_session").unwrap();
462
463        let event = ProfileEvent {
464            name: "test_event".to_string(),
465            category: "test".to_string(),
466            start_us: 0,
467            duration_us: 1,
468            thread_id: 0,
469            operation_count: Some(1),
470            flops: Some(100),
471            bytes_transferred: Some(1024),
472            stack_trace: Some("test trace".to_string()),
473        };
474
475        registry.record_event_all(&event).unwrap();
476        registry.stop_session_all("test_session").unwrap();
477
478        let stats = registry.get_all_statistics();
479        assert_eq!(stats.get("test_tool").unwrap().events_recorded, 1);
480        assert_eq!(stats.get("test_tool").unwrap().sessions_completed, 1);
481    }
482
483    #[test]
484    fn test_example_tool_export() {
485        let mut tool = ExampleCustomTool::new("test".to_string(), "1.0.0".to_string());
486        let config = ToolConfig::default();
487
488        tool.initialize(&config).unwrap();
489        tool.start_session("test").unwrap();
490
491        let event = ProfileEvent {
492            name: "test_event".to_string(),
493            category: "test".to_string(),
494            start_us: 0,
495            duration_us: 1,
496            thread_id: 0,
497            operation_count: Some(1),
498            flops: Some(100),
499            bytes_transferred: Some(1024),
500            stack_trace: Some("test trace".to_string()),
501        };
502
503        tool.record_event(&event).unwrap();
504
505        let json_data = tool.export_data(&ExportFormat::Json).unwrap();
506        assert!(!json_data.is_empty());
507
508        let csv_data = tool.export_data(&ExportFormat::Csv).unwrap();
509        assert!(!csv_data.is_empty());
510
511        tool.stop_session("test").unwrap();
512        tool.cleanup().unwrap();
513    }
514
515    #[test]
516    fn test_tool_config_serialization() {
517        let config = ToolConfig {
518            name: "test_tool".to_string(),
519            version: "1.0.0".to_string(),
520            enabled: true,
521            sampling_rate: 0.5,
522            buffer_size: 2048,
523            output_path: Some(std::env::temp_dir().join("test").display().to_string()),
524            custom_options: {
525                let mut opts = HashMap::new();
526                opts.insert("key1".to_string(), "value1".to_string());
527                opts.insert("key2".to_string(), "value2".to_string());
528                opts
529            },
530        };
531
532        let json = serde_json::to_string(&config).unwrap();
533        let deserialized: ToolConfig = serde_json::from_str(&json).unwrap();
534
535        assert_eq!(config.name, deserialized.name);
536        assert_eq!(config.version, deserialized.version);
537        assert_eq!(config.enabled, deserialized.enabled);
538        assert_eq!(config.sampling_rate, deserialized.sampling_rate);
539        assert_eq!(config.buffer_size, deserialized.buffer_size);
540        assert_eq!(config.output_path, deserialized.output_path);
541        assert_eq!(config.custom_options, deserialized.custom_options);
542    }
543
544    #[test]
545    fn test_global_api_functions() {
546        let tool = create_example_tool("global_test".to_string(), "1.0.0".to_string());
547        let config = ToolConfig::default();
548
549        assert!(register_custom_tool(tool, config).is_ok());
550        assert!(list_custom_tools().contains(&"global_test".to_string()));
551
552        assert!(initialize_custom_tools().is_ok());
553        assert!(start_custom_tool_session("global_session").is_ok());
554
555        let event = ProfileEvent {
556            name: "global_event".to_string(),
557            category: "test".to_string(),
558            start_us: 0,
559            duration_us: 1,
560            thread_id: 0,
561            operation_count: Some(1),
562            flops: Some(100),
563            bytes_transferred: Some(1024),
564            stack_trace: Some("test trace".to_string()),
565        };
566
567        assert!(record_custom_tool_event(&event).is_ok());
568        assert!(stop_custom_tool_session("global_session").is_ok());
569
570        let stats = get_custom_tool_statistics();
571        assert!(stats.contains_key("global_test"));
572
573        assert!(unregister_custom_tool("global_test").is_ok());
574    }
575}