Skip to content

API for Graphs

Observium offers an HTTP GET-based API that allows users to generate and display a variety of graphs from RRDs. This API is versatile and can be used to produce single-entity graphs, such as individual port or device statistics, as well as multi-entity graphs that combine data from multiple sources.

Authentication

The API currently supports HTTP basic authentication for existing Observium users. This enables authentication against various existing systems, including LDAP, RADIUS, and Observium's own MySQL authentication database.

To authenticate, use the following example:

curl -u <username>:<password> http://observium.domain.com/graph.php?<ARGUMENTS>

Basic Operation

The Graph API can be accessed through the graph.php script, which uses GET variables to pass arguments. You must provide the following parameters at a minimum: type, from, to, height, and width. Many graph types also require one or more id values, such as a port's ID. Device graphs accept the device parameter.

Typically, the graph type consists of the entity type and the specific graph type for that entity. For example, port_bits refers to the bits graph type for the ports entity type and multi-port_bits refers to the bits graph type covering multiple port entities. Multi-entity graph types expect a list of comma-separated entity IDs as the id parameter.

Time Definition

There are two ways to define the time range for the graphs: using the from and to parameters, or using the period parameter.

Datetime Format

The from and to parameters allow you to specify exact start and end times for the graph. The format used for these arguments can be either UNIX time in seconds or using AT-style syntax.

Examples:

  • from=-1d&to=now: Graph starting from 24 hours ago until now
  • from=1629129600&to=1629216000: Graph starting from UNIX timestamp 1629129600 to 1629216000

Period Format

Alternatively, you can use the period parameter to specify a time range for the graph, ending at the current time. The period parameter accepts an integer value representing the duration of the graph in seconds. The end time is always the current time, while the start time is calculated as the current time minus the provided duration.

Examples:

  • period=3600: Graph for the last hour (1 hour * 60 minutes * 60 seconds)
  • period=86400: Graph for the last day (24 hours * 60 minutes * 60 seconds)
  • period=604800: Graph for the last week (7 days * 24 hours * 60 minutes * 60 seconds)

Using the period parameter simplifies the process of generating graphs for a relative duration ending at the current time. Note that the period parameter should not be used together with the from and to parameters.

Parameters

Parameter Description Example
type The graph type (e.g., port_bits, device_bits, storage_usage) type=port_bits
from The graph start time (UNIXTIME in seconds or AT-style syntax) from=-8h
to The graph end time (UNIXTIME in seconds or AT-style syntax) to=now
id The ID of the entity (e.g., port or device); for multi-entity graphs, use a comma-separated list id=1,2,3
height The height of the graph in pixels height=300
width The width of the graph in pixels width=800
device The device ID for device-specific graphs device=1
legend Show or hide the legend (default: yes) legend=no
title Show or hide the title (default: yes) title=no

Examples

Below are some examples of how you might use the Graph API with different parameters:

  • Display the bits graph for a specific port: 

    curl -u <username>:<password> http://observium.domain.com/graph.php?type=port_bits&id=<PORT_ID>&from=-1d&to=now&height=300&width=800

  • Display the bits graph for a specific device: 

    curl -u <username>:<password> http://observium.domain.com/graph.php?type=device_bits&device=<DEVICE_ID>&from=-1d&to=now&height=300&width=800

  • Display the storage usage graph for a specific storage entity: 

    curl -u <username>:<password> http://observium.domain.com/graph.php?type=storage_usage&id=<STORAGE_ID>&from=-1d&to=now&height=300&width=800

  • Display a multi-entity bits graph for multiple ports: 

    curl -u <username>:<password> http://observium.domain.com/graph.php?type=multiport_bits&id=<PORT_ID1>,<PORT_ID2>,<PORT_ID3>&from=-1d&to=now&height=300&width=800

In this example, <PORT_ID1>, <PORT_ID2>, and <PORT_ID3> represent the IDs of the ports you want to include in the multi-entity graph.

By utilizing the Observium Graph API, you can easily generate and display various types of graphs formonitoring and analyzing your network devices and their performance. The flexibility of the API allows you to create customized graphs for single or multiple entities, enabling you to better understand the behavior and trends in your network infrastructure.