0
# Plugin Management
1

2
Plugin lifecycle management for Grafana instances. This includes installing and uninstalling plugins from the Grafana plugin store, listing installed plugins, health checks, and metrics collection.
3

4
## Capabilities
5

6
### Plugin Listing
7

8
List all installed plugins on the Grafana instance, with options to filter and retrieve detailed plugin information.
9

10
```python { .api }
11
def list(self):
12
    """
13
    Return list of all installed plugins.
14
    
15
    Returns:
16
        list: List of plugin objects with metadata
17
    """
18

19
def by_id(self, plugin_id: str):
20
    """
21
    Return single plugin item selected by plugin identifier.
22
    
23
    Parameters:
24
        plugin_id (str): The plugin identifier
25
        
26
    Returns:
27
        dict: Plugin object with metadata
28
        
29
    Raises:
30
        KeyError: If plugin with specified ID is not found
31
    """
32
```
33

34
### Plugin Installation
35

36
Install and uninstall plugins from the Grafana plugin store with error handling options.
37

38
```python { .api }
39
def install(self, plugin_id: str, version: Optional[str] = None, errors: str = "raise"):
40
    """
41
    Install a 3rd-party plugin from the plugin store.
42
    
43
    Parameters:
44
        plugin_id (str): The plugin identifier to install
45
        version (str, optional): Specific version to install. Defaults to latest
46
        errors (str): Error handling mode - "raise" or "ignore"
47
        
48
    Returns:
49
        dict or None: Installation result or None if ignored
50
        
51
    Raises:
52
        GrafanaClientError: If installation fails and errors="raise"
53
        ValueError: If errors parameter is invalid
54
    """
55

56
def uninstall(self, plugin_id: str, errors: str = "raise"):
57
    """
58
    Uninstall a 3rd-party plugin from the Grafana instance.
59
    
60
    Parameters:
61
        plugin_id (str): The plugin identifier to uninstall
62
        errors (str): Error handling mode - "raise" or "ignore"
63
        
64
    Returns:
65
        dict or None: Uninstallation result or None if ignored
66
        
67
    Raises:
68
        GrafanaClientError: If uninstallation fails and errors="raise"
69
        ValueError: If errors parameter is invalid
70
    """
71
```
72

73
### Plugin Health and Metrics
74

75
Monitor plugin health and collect metrics for operational insights.
76

77
```python { .api }
78
def health(self, plugin_id: str):
79
    """
80
    Run a health check probe on the designated plugin.
81
    
82
    Parameters:
83
        plugin_id (str): The plugin identifier to check
84
        
85
    Returns:
86
        dict: Health check results
87
    """
88

89
def metrics(self, plugin_id: str):
90
    """
91
    Inquire metrics of the designated plugin.
92
    
93
    Parameters:
94
        plugin_id (str): The plugin identifier to get metrics for
95
        
96
    Returns:
97
        dict: Plugin metrics data
98
    """
99
```
100

101
## Usage Examples
102

103
### Basic Plugin Management
104

105
```python
106
from grafana_client import GrafanaApi, TokenAuth
107

108
# Create API client
109
auth = TokenAuth(token="your-grafana-api-token")
110
api = GrafanaApi(auth=auth, host="your-grafana-host")
111

112
# List all installed plugins
113
plugins = api.plugin.list()
114
for plugin in plugins:
115
    print(f"Plugin: {plugin['id']} - {plugin['name']} v{plugin['info']['version']}")
116

117
# Get specific plugin details
118
try:
119
    plugin_info = api.plugin.by_id("grafana-clock-panel")
120
    print(f"Found plugin: {plugin_info['name']}")
121
except KeyError:
122
    print("Plugin not found")
123

124
# Install a plugin
125
try:
126
    result = api.plugin.install("grafana-clock-panel")
127
    print(f"Plugin installed: {result}")
128
except Exception as e:
129
    print(f"Installation failed: {e}")
130

131
# Check plugin health
132
health_status = api.plugin.health("grafana-clock-panel")
133
print(f"Plugin health: {health_status}")
134

135
# Get plugin metrics
136
metrics = api.plugin.metrics("grafana-clock-panel")
137
print(f"Plugin metrics: {metrics}")
138

139
# Uninstall a plugin
140
api.plugin.uninstall("grafana-clock-panel")
141
print("Plugin uninstalled")
142
```
143

144
### Error Handling
145

146
```python
147
# Install plugin with error ignoring
148
result = api.plugin.install("some-plugin", errors="ignore")
149
if result is None:
150
    print("Installation was skipped or failed silently")
151

152
# Install specific version
153
api.plugin.install("grafana-clock-panel", version="1.3.0")
154
```