tessl/pypi-grafana-client
A client library for accessing the Grafana HTTP API, written in Python
—
Pending
library-elements.mddocs/
Library Elements
Management of reusable library panels and variables that can be shared across multiple dashboards. Library elements promote consistency and efficiency by allowing you to create once and reuse across your Grafana instance.
Note: Library elements are only available in Grafana 8.2 and later versions.
Capabilities
Element Constants
Library element type constants for creating and filtering elements.
Panel: int = 1 # Library panel type
Variable: int = 2 # Library variable typeElement Retrieval
Retrieve library elements by identifier, name, or get connection information showing which dashboards use them.
def get_library_element(self, element_uid: str):
"""
Get a library element by its UID.
Parameters:
element_uid (str): The unique identifier of the library element
Returns:
dict: Library element data including model and metadata
Raises:
DeprecationWarning: If Grafana version is earlier than 8.2
"""
def get_library_element_by_name(self, element_name: str):
"""
Get a library element by its name.
Parameters:
element_name (str): The name of the library element
Returns:
dict: Library element data including model and metadata
Raises:
DeprecationWarning: If Grafana version is earlier than 8.2
"""
def get_library_element_connections(self, element_uid: str):
"""
Get connections showing which dashboards use this library element.
Parameters:
element_uid (str): The unique identifier of the library element
Returns:
dict: Connection information with dashboard references
Raises:
DeprecationWarning: If Grafana version is earlier than 8.2
"""Element Management
Create, update, and delete library elements with comprehensive configuration options.
def create_library_element(self, model: dict, name: Optional[str] = None,
kind: int = 1, uid: Optional[str] = None,
folder_uid: Optional[str] = None):
"""
Create a new library element.
Parameters:
model (dict): The element model (panel or variable configuration)
name (str, optional): Name for the element. Extracted from model if not provided
kind (int): Element type - Panel (1) or Variable (2). Default is Panel
uid (str, optional): Custom UID. Generated if not provided
folder_uid (str, optional): Folder to store element in
Returns:
dict: Created library element with assigned UID and metadata
Raises:
DeprecationWarning: If Grafana version is earlier than 8.2
"""
def update_library_element(self, uid: str, model: dict, name: Optional[str] = None,
kind: int = 1, folder_uid: Optional[str] = None,
version: Optional[int] = None):
"""
Update an existing library element.
Parameters:
uid (str): The UID of the element to update
model (dict): Updated element model
name (str, optional): Updated name
kind (int): Element type - Panel (1) or Variable (2)
folder_uid (str, optional): Move to different folder
version (int, optional): Element version for optimistic locking
Returns:
dict: Updated library element
Raises:
DeprecationWarning: If Grafana version is earlier than 8.2
ValueError: If version is required but not provided
"""
def delete_library_element(self, element_uid: str):
"""
Delete a library element.
Parameters:
element_uid (str): The UID of the element to delete
Returns:
dict: Deletion result
Raises:
DeprecationWarning: If Grafana version is earlier than 8.2
"""Element Listing and Search
List and search library elements with comprehensive filtering and pagination options.
def list_library_elements(self, search_string: Optional[str] = None,
kind: Optional[int] = None, sort_direction: Optional[str] = None,
type_filter: Optional[str] = None, exclude_uid: Optional[str] = None,
folder_filter: Optional[str] = None, per_page: Optional[int] = None,
page: Optional[int] = None):
"""
List library elements with optional search and filtering.
Parameters:
search_string (str, optional): Search term for element names
kind (int, optional): Filter by element type (Panel=1, Variable=2)
sort_direction (str, optional): Sort direction ("asc" or "desc")
type_filter (str, optional): Filter by panel type
exclude_uid (str, optional): Exclude element with this UID
folder_filter (str, optional): Filter by folder
per_page (int, optional): Results per page for pagination
page (int, optional): Page number for pagination
Returns:
dict: List of library elements with pagination metadata
Raises:
DeprecationWarning: If Grafana version is earlier than 8.2
"""Usage Examples
Creating Library Elements
from grafana_client import GrafanaApi, TokenAuth
# Create API client
auth = TokenAuth(token="your-grafana-api-token")
api = GrafanaApi(auth=auth, host="your-grafana-host")
# Create a library panel
panel_model = {
"type": "stat",
"title": "Server CPU Usage",
"targets": [
{
"expr": "cpu_usage_percent",
"refId": "A"
}
],
"fieldConfig": {
"defaults": {
"unit": "percent",
"thresholds": {
"steps": [
{"color": "green", "value": None},
{"color": "yellow", "value": 70},
{"color": "red", "value": 90}
]
}
}
}
}
# Create the library panel
library_panel = api.libraryelement.create_library_element(
model=panel_model,
name="CPU Usage Panel",
kind=api.libraryelement.Panel,
folder_uid="monitoring-folder-uid"
)
print(f"Created library panel: {library_panel['uid']}")
# Create a library variable
variable_model = {
"type": "query",
"name": "server",
"label": "Server",
"query": "label_values(up, instance)",
"multi": True,
"includeAll": True
}
library_variable = api.libraryelement.create_library_element(
model=variable_model,
name="Server Selection Variable",
kind=api.libraryelement.Variable
)
print(f"Created library variable: {library_variable['uid']}")Managing Library Elements
# List all library panels
panels = api.libraryelement.list_library_elements(
kind=api.libraryelement.Panel,
sort_direction="asc"
)
for panel in panels['elements']:
print(f"Panel: {panel['name']} - UID: {panel['uid']}")
# Search for CPU-related elements
cpu_elements = api.libraryelement.list_library_elements(
search_string="CPU",
per_page=10,
page=1
)
# Get specific library element
element_uid = "library-panel-uid"
element = api.libraryelement.get_library_element(element_uid)
print(f"Element: {element['name']} - Type: {element['kind']}")
# Check which dashboards use this element
connections = api.libraryelement.get_library_element_connections(element_uid)
for connection in connections:
print(f"Used in dashboard: {connection['connectionUid']}")
# Update library element
updated_model = element['model']
updated_model['title'] = "Updated CPU Usage Panel"
api.libraryelement.update_library_element(
uid=element_uid,
model=updated_model,
name="Updated CPU Usage Panel"
)
# Delete library element (only if not in use)
api.libraryelement.delete_library_element(element_uid)
print("Library element deleted")Working with Library Variables
# Create a complex library variable
datasource_variable = {
"type": "datasource",
"name": "datasource",
"label": "Data Source",
"query": "prometheus",
"multi": False,
"includeAll": False,
"current": {
"value": "prometheus-uid",
"text": "Prometheus"
}
}
library_var = api.libraryelement.create_library_element(
model=datasource_variable,
name="Prometheus Datasource Variable",
kind=api.libraryelement.Variable,
folder_uid="variables-folder"
)
# List only library variables
variables = api.libraryelement.list_library_elements(
kind=api.libraryelement.Variable
)
for var in variables['elements']:
print(f"Variable: {var['name']} - Type: {var['model']['type']}")Install with Tessl CLI
npx tessl i tessl/pypi-grafana-client@5.0.1