Add get_series endpoint

Author: nikola-milikic

examples/get_data_promql_advanced.py

@@ -110,7 +110,7 @@ def print_prometheus_results_as_table(results):
 #
 if ok:
     #
-    # Read response. The JSON looks like this:
+    # Read the response. The JSON looks like this:
     #
     # {
     #     "data":   {

examples/get_data_promql_simple.py

@@ -95,7 +95,7 @@ def print_prometheus_results_as_table(results):
 #
 if ok:
     #
-    # Read response. The JSON looks like this:
+    # Read the response. The JSON looks like this:
     #
     # {
     #     "data":   {

examples/get_series.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+#
+# This script demonstrates how to use the `get_series` function to retrieve metadata
+# about time series that match a set of label matchers.
+#
+
+import sys
+from sdcclient import SdcClient
+
+def render_json_as_table(results):
+    if not data or len(data) == 0:
+        print("No series found for the given matchers.")
+        return
+
+    # Extract all keys from the JSON objects
+    keys = list(results[0].keys())
+
+    # Calculate the maximum width for each column
+    column_widths = {key: max(len(key), max(len(str(row.get(key, ""))) for row in results)) for key in keys}
+
+    # Create a horizontal separator
+    separator = "+".join("-" * (column_widths[key] + 2) for key in keys)
+
+    # Create the header row
+    header = "|".join(f" {key.ljust(column_widths[key])} " for key in keys)
+
+    # Create the rows for each JSON object
+    rows = []
+    for row in results:
+        rows.append("|".join(f" {str(row.get(key, '')).ljust(column_widths[key])} " for key in keys))
+
+    # Combine everything into a table
+    print(f"+{separator}+\n|{header}|\n+{separator}+\n" + "\n".join(f"|{row}|" for row in rows) + f"\n+{separator}+")
+
+
+#
+# Parse arguments
+#
+if len(sys.argv) != 2:
+    print(('usage: %s <sysdig-token>' % sys.argv[0]))
+    print('You can find your token at https://app.sysdigcloud.com/#/settings/user')
+    sys.exit(1)
+
+sdc_token = sys.argv[1]
+
+sdclient = SdcClient(sdc_token)
+
+#
+# Matchers to filter the series. Example: `up` and `process_start_time_seconds{job="prometheus"}`
+#
+match = [
+    'up',
+    'process_start_time_seconds{job="prometheus"}'
+]
+
+#
+# Optional time range
+#
+start = None  # Replace with a timestamp if needed
+end = None    # Replace with a timestamp if needed
+
+#
+# Optional limit
+#
+limit = 5  # Set to None to disable the limit
+
+#
+# Fetch series
+#
+ok, response_json = sdclient.get_series(match, start=start, end=end, limit=limit)
+
+#
+# Show the result
+#
+if ok:
+    #
+    # Read the response. The JSON looks like this:
+    #
+    # {
+    #     "data":   [
+    #         {
+    #           "__name__": "up",
+    #           "_sysdig_custom_metric": "true",
+    #           "_sysdig_datasource": "prometheus_remote_write",
+    #           "agent_version": "thereal-test-x86_64",
+    #           "instance": "default.test.svc.cluster.local:9544",
+    #           "jenkins_job_build_number": "1234",
+    #           "job": "default-test-20250428112951594",
+    #           "remote_write": "true"
+    #         }
+    #     ],
+    #     "status": "success"
+    # }
+    #
+    data = response_json.get("data", {})
+    render_json_as_table(data)
+else:
+    print("Error retrieving series:", response_json)

sdcclient/_common.py

@@ -510,6 +510,37 @@ def get_data_promql_instant(self, query, time=None, timeout=None, limit=None):
         res = self.http.get(url, headers=self.hdrs, params=params)
         return self._request_result(res)
 
+    def get_series(self, match, start=None, end=None, limit=None):
+        '''**Description**
+            Retrieve metadata about time series that match a set of label matchers.
+
+        **Arguments**
+            - **match**: a list of PromQL matchers (e.g., `['up', 'node_cpu_seconds_total']`).
+            - **start**: the inclusive start timestamp of the series query as RFC3339 or a unix timestamp.
+            - **end**: the inclusive end timestamp of the series query as RFC3339 or a unix timestamp.
+            - **limit**: the maximum number of returned series. The limit is capped at 10,000. To disable the limit, set the value to 0.
+
+        **Success Return Value**
+            A list of series that match the provided matchers.
+
+        **Examples**
+            - `examples/get_series.py`
+        '''
+        params = {
+                "match[]": match, # `match` should be a list of matchers
+        }
+
+        if start:
+            params["start"] = start
+        if end:
+            params["end"] = end
+        if limit:
+            params["limit"] = limit
+
+        url = f"{self.url}/prometheus/api/v1/series"
+        res = self.http.get(url, headers=self.hdrs, params=params)
+        return self._request_result(res)
+
     def get_sysdig_captures(self, from_sec=None, to_sec=None, scope_filter=None):
         '''**Description**
             Returns the list of sysdig captures for the user.