Reporting API

Note

You can generate reports (PDF format) directly with the API

Endpoints

  • API can be reached at https://<<datasentinel_platform_server>>/ds-api/

Note

A toolkit, wich provides examples of use, is available on Github

The toolkit is installed by default on the on-premises platform (/datasentinel/soft/datasentinel_toolkit)

User token generation

In order to use reporting API, you need to generate an access token. The access token is valid for 1 day

POST /ds-api/user-token
  • Authentication

    You need to be authenticated with your username and password
    The user must have data admin profile with admin privilege
  • Example

curl -u myUser:myPassword -k -X POST https://<<datasentinel_platform_server>>/ds-api/user-token
  • Response

{
  "user-token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1ODAyMTYyMjQsImlhdCI6MTU4MDEyOTgxOSwiZGF0YWJhc2UiOiJNYWluIE9yZy4iLCJlbWFpbCI6InRlc3RAZGF0YXNlbnRpbmVsLmlvIiwidXNlciI6InRlc3QifQ.JMDvq2JPcqz9M0_it_0UtP9y79dClVwx9pDEzCl9HTk"
}

Display User token

GET /ds-api/user-token?token={user-token}
  • Path parameter:

    The token
  • Example

export TOKEN=<<user_token>>
curl -u myUser:myPassword -k -X GET https://<<datasentinel_platform_server>>/ds-api/user-token?token=$TOKEN
  • Response

{
    "email": "contact@datasentinel.io",
    "expire_time": "2020-04-28 13:58:53",
    "organization_name": "ds-data",
    "user": "datasentinel"
}

Session history report

Report example PDF

POST /ds-api/activity/session-history-report
  • Example

export TOKEN=<<user_token>>
curl -k --header "user-token: $TOKEN" --header 'Content-Type: application/json' --request POST 'https://app.datasentinel.io/ds-api/activity/session-history-report' -d @body.json -o sessions.pdf
  • Request example (body.json)

{
    "utc_time": false,
    "from": "2022-02-10 08:00:00",
    "to": "2022-02-10 09:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench",
    "group": "wait_event_type",
    "sub_group": "wait_event",
    "limit": 20
}
  • Parameters:

    utc_time [Optional] Default: true
    When false , the timezone taken into account will depend on the timezone of the platform

    from: The start date.
    to: The end date.
    Date format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS

    filters: Array of tags (“tag” : Tag name, “value”: Tag value)
    The report can include multiple instances (example: “tag” : “environment”, “value”: “production”)

    database [Optional] Default: All.
    Allows you to focus on a database

    group [Optional] Default: wait_event_type.
    sub_group [Optional] Default: wait_event.
    2 dimensions are always computed: wait_event_type and wait_event

    You can add 2 other dimensions. It can be
    - a global tag (pg_instance, server, pg_version)
    - a custom tag
    - an automatic tag issued from the active session sampling process on pg_stat_activity:
    (application_name, client_host_name, command_type, database, process_id, query_md5_id, user_name)


    limit [Optional] Default: 20. Limit the number of lines displayed

If you want to send the report directly by email, you need to add these parameters


report_type : “email”

subject: [Optional] Default: [Datasentinel] Top queries report
The email subject

recipients: email array
You can set multiple emails
  • Example (body.json)

{
    "utc_time": true,
    "from": "2020-02-28 00:00:00",
    "to": "2020-02-29 01:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench",
    "by": "user_name",
    "limit": 20,
    "report_type": "email",
    "subject": "[Datasentinel] Session history report",
    "recipients": ["contact@datasentinel.io"]
}

Top queries report

Report example PDF

POST /ds-api/activity/top-queries-report
  • Example

export TOKEN=<<user_token>>
curl -k --header "user-token: $TOKEN" --header 'Content-Type: application/json' --request POST 'https://app.datasentinel.io/ds-api/activity/top-queries-report' -d @body.json -o top-queries.pdf
  • Request example (body.json)

{
    "utc_time": false,
    "from": "2022-02-10 08:00:00",
    "to": "2022-02-10 09:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench",
    "by": "total_time",
    "limit": 20
}
  • Parameters:

    utc_time [Optional] Default: true
    When false , the timezone taken into account will depend on the timezone of the platform

    from: The start date.
    The format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS
    to: The end date.
    The format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS

    filters: Array of tags (“tag” : Tag name, “value”: Tag value)
    The report can include multiple instances (example: “tag” : “environment, “value”: “production”)

    database [Optional] Default: All.
    Allows you to focus on a database

    by [Optional] Default: total_time.
    Dimension on which the report is based

    Possible values:
    - calls, local_blks_dirtied, local_blks_hit, local_blks_read, local_blks_written, rows, shared_blks_dirtied,
    - shared_blks_hit, shared_blks_read, shared_blks_written,
    - temp_blks_read, temp_blks_written, total_time, blk_read_time, blk_write_time, wal_bytes

    limit [Optional] Default: 20. Limit the number of queries displayed

If you want to send the report directly by email, you need to add these parameters


report_type : “email”

subject: [Optional] Default: [Datasentinel] Top queries report
The email subject

recipients: email array
You can set multiple emails
  • Example (body.json)

{
    "utc_time": true,
    "from": "2020-02-28 00:00:00",
    "to": "2020-02-29 01:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench",
    "by": "total_time",
    "limit": 20,
    "report_type": "email",
    "subject": "[Datasentinel] Top queries report",
    "recipients": ["contact@datasentinel.io"]
}

Table report

Report example PDF

POST /ds-api/activity/table-report
  • Example

export TOKEN=<<user_token>>
curl -k --header "user-token: $TOKEN" --header 'Content-Type: application/json' --request POST 'https://app.datasentinel.io/ds-api/activity/table-report' -d @body.json -o table_report.pdf
  • Request example (body.json)

{
    "utc_time": false,
    "from": "2022-02-10 08:00:00",
    "to": "2022-02-10 09:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench",
    "by": "heap_blks_hit",
    "index_by": "idx_blks_hit",
    "limit": 25
}
  • Parameters:

    utc_time [Optional] Default: true
    When false , the timezone taken into account will depend on the timezone of the platform

    from: The start date.
    to: The end date.
    Date format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS

    filters: Array of tags (“tag” : Tag name, “value”: Tag value)
    The report can include multiple instances (example: “tag” : “environment”, “value”: “production”)

    database [Optional] Default: All.
    Allows you to focus on a database

    by [Optional] Default: heap_blks_read.
    Dimension on which table metrics are sorted

    Possible values:
    - heap_blks_hit, heap_blks_read, idx_blks_hit, idx_blks_read, idx_scan, idx_tup_fetch
    - n_tup_del, n_tup_hot_upd, n_tup_ins, n_tup_upd, reltuples, seq_scan, seq_tup_read, size
    - tidx_blks_hit, tidx_blks_read, toast_blks_hit, toast_blks_read
    - n_live_tup, n_dead_tup, n_mod_since_analyze

    index_by [Optional] Default: idx_blks_read.
    Dimension on which index metrics are sorted

    Possible values:
    - idx_blks_hit, idx_blks_read, idx_scan, idx_tup_fetch, idx_tup_read, size

    limit [Optional] Default: 20. Limit the number of lines displayed

If you want to send the report directly by email, you need to add these parameters


report_type : “email”

subject: [Optional] Default: [Datasentinel] Top queries report
The email subject

recipients: email array
You can set multiple emails
  • Example (body.json)

{
    "utc_time": true,
    "from": "2020-02-28 00:00:00",
    "to": "2020-02-29 01:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench",
    "report_type": "email",
    "subject": "[Datasentinel] Top queries report",
    "recipients": ["contact@datasentinel.io"]
}

Instance report

Report example PDF

POST /ds-api/activity/instance-report
  • Example

export TOKEN=<<user_token>>
curl -k --header "user-token: $TOKEN" --header 'Content-Type: application/json' --request POST 'https://app.datasentinel.io/ds-api/activity/instance-report' -d @body.json -o instance_report.pdf
  • Request example (body.json)

{
    "utc_time": false,
    "from": "2022-02-10 08:00:00",
    "to": "2022-02-10 09:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench"
}
  • Parameters:

    utc_time [Optional] Default: true
    When false , the timezone taken into account will depend on the timezone of the platform

    from: The start date.
    to: The end date.
    Date format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS

    filters: Array of tags (“tag” : Tag name, “value”: Tag value)
    The report can include multiple instances (example: “tag” : “environment”, “value”: “production”)

    database [Optional] Default: All.
    Allows you to focus on a database


If you want to send the report directly by email, you need to add these parameters


report_type : “email”

subject: [Optional] Default: [Datasentinel] Top queries report
The email subject

recipients: email array
You can set multiple emails
  • Example (body.json)

{
    "utc_time": true,
    "from": "2020-02-28 00:00:00",
    "to": "2020-02-29 01:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench",
    "report_type": "email",
    "subject": "[Datasentinel] Top queries report",
    "recipients": ["contact@datasentinel.io"]
}

Query report

Report example PDF

POST /ds-api/activity/query-report
  • Example

export TOKEN=<<user_token>>
curl -k --header "user-token: $TOKEN" --header 'Content-Type: application/json' --request POST 'https://app.datasentinel.io/ds-api/activity/query-report' -d @body.json -o query_report.pdf
  • Request example (body.json)

{
    "utc_time": false,
    "from": "2022-02-10 08:00:00",
    "to": "2022-02-10 09:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "query_md5_id": "02f32f0590b9ab78655de3fb7354"
    "database": "pgbench"
}
  • Parameters:

    utc_time [Optional] Default: true
    When false , the timezone taken into account will depend on the timezone of the platform

    from: The start date.
    to: The end date.
    Date format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS

    filters: Array of tags (“tag” : Tag name, “value”: Tag value)
    The report can include multiple instances (example: “tag” : “environment”, “value”: “production”)

    query_md5_id: query internal identifier computed by Datasentinel visible on the UI

    database [Optional] Default: All.
    Allows you to focus on a database


If you want to send the report directly by email, you need to add these parameters


report_type : “email”

subject: [Optional] Default: [Datasentinel] Top queries report
The email subject

recipients: email array
You can set multiple emails
  • Example (body.json)

{
    "utc_time": true,
    "from": "2020-02-28 00:00:00",
    "to": "2020-02-29 01:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "query_md5_id": "02f32f0590b9ab78655de3fb7354"
    "database": "pgbench",
    "report_type": "email",
    "subject": "[Datasentinel] Top queries report",
    "recipients": ["contact@datasentinel.io"]
}

Server report

Report example PDF

POST /ds-api/activity/server-report
  • Example

export TOKEN=<<user_token>>
curl -k --header "user-token: $TOKEN" --header 'Content-Type: application/json' --request POST 'https://app.datasentinel.io/ds-api/activity/server-report' -d @body.json -o server_report.pdf
  • Request example (body.json)

{
    "utc_time": false,
    "from": "2022-02-10 08:00:00",
    "to": "2022-02-10 09:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ]
}
  • Parameters:

    utc_time [Optional] Default: true
    When false , the timezone taken into account will depend on the timezone of the platform

    from: The start date.
    to: The end date.
    Date format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS

    filters: Array of tags (“tag” : Tag name, “value”: Tag value)
    The report can include multiple instances (example: “tag” : “environment”, “value”: “production”)


If you want to send the report directly by email, you need to add these parameters


report_type : “email”

subject: [Optional] Default: [Datasentinel] Top queries report
The email subject

recipients: email array
You can set multiple emails
  • Example (body.json)

{
    "utc_time": true,
    "from": "2020-02-28 00:00:00",
    "to": "2020-02-29 01:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "report_type": "email",
    "subject": "[Datasentinel] Top queries report",
    "recipients": ["contact@datasentinel.io"]
}

Data size report

Report example PDF

POST /ds-api/activity/data-size-report
  • Example

export TOKEN=<<user_token>>
curl -k --header "user-token: $TOKEN" --header 'Content-Type: application/json' --request POST 'https://app.datasentinel.io/ds-api/activity/data-size-report' -d @body.json -o data_size_report.pdf
  • Request example (body.json)

{
    "utc_time": false,
    "from": "2022-02-10 08:00:00",
    "to": "2022-02-10 09:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench"
}
  • Parameters:

    utc_time [Optional] Default: true
    When false , the timezone taken into account will depend on the timezone of the platform

    from: The start date.
    to: The end date.
    Date format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS

    filters: Array of tags (“tag” : Tag name, “value”: Tag value)
    The report can include multiple instances (example: “tag” : “environment”, “value”: “production”)

    database [Optional] Default: All.
    Allows you to focus on a database


If you want to send the report directly by email, you need to add these parameters


report_type : “email”

subject: [Optional] Default: [Datasentinel] Data size report
The email subject

recipients: email array
You can set multiple emails
  • Example (body.json)

{
    "utc_time": true,
    "from": "2020-02-28 00:00:00",
    "to": "2020-02-29 01:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench",
    "report_type": "email",
    "subject": "[Datasentinel] Data size report",
    "recipients": ["contact@datasentinel.io"]
}

Full report

Report example PDF

POST /ds-api/activity/full-report
  • Example

export TOKEN=<<user_token>>
curl -k --header "user-token: $TOKEN" --header 'Content-Type: application/json' --request POST 'https://app.datasentinel.io/ds-api/activity/full-report' -d @body.json -o data_size_report.pdf
  • Request example (body.json)

{
    "utc_time": false,
    "from": "2022-02-10 08:00:00",
    "to": "2022-02-10 09:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "database": "pgbench"
}
  • Parameters:

    utc_time [Optional] Default: true
    When false , the timezone taken into account will depend on the timezone of the platform

    from: The start date.
    to: The end date.
    Date format can be YYYY-MM-DD, YYYY-MM-DD HH:MI, YYYY-MM-DD HH:MI:SS

    filters: Array of tags (“tag” : Tag name, “value”: Tag value)
    The report can include multiple instances (example: “tag” : “environment”, “value”: “production”)

    database [Optional] Default: All.
    Allows you to focus on a database

If you want to send the report directly by email, you need to add these parameters


report_type : “email”

subject: [Optional] Default: [Datasentinel] Full report
The email subject

recipients: email array
You can set multiple emails
  • Example (body.json)

{
    "utc_time": true,
    "from": "2020-02-28 00:00:00",
    "to": "2020-02-29 01:00:00",
    "filters": [
        {
            "tag": "pg_instance",
            "value": "pg-crm-0926@:9342"
        }
    ],
    "report_type": "email",
    "subject": "[Datasentinel] Report activity",
    "recipients": ["contact@datasentinel.io"]
}