PGX 21.1.1
Documentation

Admin API

This chapter shows how to use PGX Admin API to inspect the server state including sessions, graphs, tasks, memory and thread pools.

Get a Server Instance

The following code gets a pgx Instance which can be local(the code below) or remote.

import oracle.pgx.api.*;

ServerInstance instance = Pgx.getInstance(Pgx.EMBEDDED_URL);
instance = pypgx.get_session(base_url= "url")

Get Inspection Data

Inspection data is information about the server state. The following code shows how to return it.

JsonNode serverState = instance.getServerState();
server_state = instance.get_server_state()

This returns a JsonNode which contains all administration information(how many graphs are loaded? how many sessions? memory usage for graphs and properties, ...)

{
    "cached_graphs": [],
    "published_graphs": [],
    "graphs_currently_loading": [],
    "sessions": [],
    "tasks": [],
    "pools": [],
    "memory": {}
}

Sessions

serverState.get("sessions") returns an array of current active sessions. Each entry contains information about a session.

     {
            "session_id": "530b5f9a-75c4-4838-9cc3-44df44b035c5",
            "source": "testServerState",
            "task_timeout_ms": 0,
            "idle_timeout_ms": 0,
            "alive_ms": 237,
            "total_analysis_time_ms": 115,
            "state": "RELEASED",
            "private_graphs": [
                {
                    "name": "anonymous_graph_1",
                    "creation_timestamp": 1589317879755,
                    "is_transient": true,
                    "memory": {
                        "topology_bytes": 46,
                        "key_mapping_bytes": 30,
                        "persistent_property_mem_bytes": 0,
                        "transient_property_mem_bytes": 0
                    },
                    "vertices_num": 1,
                    "edges_num": 0,
                    "persistent_vertex_properties": [],
                    "persistent_edge_properties": [],
                    "transient_vertex_properties": [],
                    "transient_edge_properties": []
                }
            ],
            "published_graphs": [
                {
                    "name": "multigraph",
                    "creation_timestamp": 1589317879593,
                    "is_transient": false,
                    "memory": {
                        "topology_bytes": 110,
                        "key_mapping_bytes": 56,
                        "persistent_property_mem_bytes": 64,
                        "transient_property_mem_bytes": 0
                    },
                    "vertices_num": 2,
                    "edges_num": 6,
                    "persistent_vertex_properties": [
                        {
                            "loaded": true,
                            "mem_size_bytes": 16,
                            "name": "tProp",
                            "type": "string"
                        }
                    ],
                    "persistent_edge_properties": [
                        {
                            "loaded": true,
                            "mem_size_bytes": 48,
                            "name": "cost",
                            "type": "double"
                        }
                    ],
                    "transient_vertex_properties": [],
                    "transient_edge_properties": []
                }
             ]
        }

The table below explains session information fields

Field Meaning
sessionID Session' ID generated by PGX server
source Descriptive string identifying the client session
task_timeout_ms Timeout to interrupt long-running tasks submitted by sessions (algorithms, I/O tasks) in milliseconds. Set to zero for infinity/no timeout
idle_timeout_ms Timeout of idling sessions in milliseconds. Set to zero for infinity/no timeout
alive_ms Session's age in milliseconds
total_analysis_time_ms Total session's executing time in milliseconds
state Current session of the session can be Idle, Submitted, released or terminating
private_graphs Session bounded graphs
published_graphs Published graphs that the session has pointer to

The is_transient field indicates if the graph is transient. A graph is transient if it was not loaded from an external source. A transient graph can for example be created using the GraphBuilder API.

Cached Graphs

The server state contains also cached graph information serverState.get("cached_graphs") which returns a collection of graphs cached in memory. Each entry contains information about a graph

{
            "name": "sf-1589317879394",
            "creation_timestamp": 1589317879394,
            "vertex_properties": [
                {
                    "loaded": true,
                    "mem_size_bytes": 478504,
                    "name": "prop1",
                    "type": "double"
                }
            ],
            "edge_properties": [
                {
                    "loaded": true,
                    "mem_size_bytes": 1197720,
                    "name": "cost",
                    "type": "double"
                },
                {
                    "loaded": true,
                    "mem_size_bytes": 598860,
                    "name": "0",
                    "type": "integer"
                }
            ],
            "memory": {
                "topology_bytes": 3921814,
                "key_mapping_bytes": 1407466,
                "property_mem_bytes": 2275084
            },
            "vertices_num": 59813,
            "edges_num": 149715
        }

The table below explains graph information fields

Field Meaning
name The graph's name
creation_timestamp The graph's creation timestamp
vertex_properties List of vertex properties, each entry contains the name, type, memory size used by the property, and a boolean flag to indicate if the property is loaded into memory
edge_properties List of edges properties, similar to vertex properties
memory Memory size used by the whole graph (topology, key mappings and properties)
vertices_num Number of vertices
edges_num Number of edges

Published Graphs

serverState.get("published_graphs") returns a list of published graphs. Each graph entry contains information about the published graph, similar to cached_graphs

Graphs Currently Loading

serverState.get("graphs_currently_loading") returns progress information about graphs which are currently loading. Each entry, corresponding to one graph, looks as follows

{
    "name": "anonymous_graph_1",
    "session_id": "530b5f9a-75c4-4838-9cc3-44df44b035c5",
    "start_loading_timestamp": 1605468453030,
    "elapsed_loading_time_ms": 281742,
    "num_vertices_read": 10000000,
    "num_edges_read": 196500000,
    "num_edge_providers_loaded": 1,
    "num_edge_providers_remaining": 9,
    "num_vertex_providers_loaded": 1,
    "num_vertex_providers_remaining": 0,
    "loading_phase": "reading edges",
    "loading_phase_start_timestamp": 1605468453085,
    "loading_phase_elapsed_time_ms": 281687,
    "loading_phase_state": "current vertex provider index: 1, number of vertices read for prorvider: 0, current edge provider index: 1, number of edges read for prorvider: 76,500,000"
}

The name field contains a temporary name of the graph. It may not be equal to the name that is assigned to graph after loading.

Fields indicating the number of read vertices and edges are updated in regular intervals of 10,000 entities.

The field loading_phase indicates the current phase during graph loading. Examples are "reading edges" or "building graph indices". For some loading phases, the field loading_phase_state contains a string with additional information on the phase. However, not all loading phases provide this additional information.

Supported Formats

graphs_currently_loading is supported for data formats CSV, ADJ_LIST, EDGE_LIST, TWO_TABLES and PG (FLAT_FILE) for homogeneous graphs and for formats CSV and RDBMS for partitioned graphs.

Tasks

serverState.get("tasks") returns the last 100 queued tasks. Each task has a type, the pool to be executed on (the task might be already executed) and other status fields ({Queued|Started|Done} time), and a sessionid if the task belongs to a session.

Memory

This section contains a map of available memories, the key is the hostname and the value is a list of current available memories(managed and unmanaged). Each entry contains how much memory is free, used and the max available.

Pools

serverState.get("pools") returns information about available thread pools per host such as type, busyTime and the sessions using this pool.