Stats

/v1/stats

Collect important stats about your Coreapp and database with the stats node. Measure the performance of your queue with current queue callback size and number of pending messages.

This document covers:

Coreapp Stats

Use the /v1/stats/app endpoint to retrieve Coreapp stats in JSON format. Coreapp stats live in memory and can be queried at regular intervals if needed.

Request

GET /v1/stats/app

Response

If successful, your request returns 200 OK and a message body containing an app object. For example, the complete response, including the app object, might look like this:

{
    "stats": {
        "app": {
            "callback_queue_size": {
                "data": [
                    {
                        "value": 450
                    }
                ],
                "help": "Current callback queue size",
                "type": "gauge"
            },
            "callback_requests": {
                "data": [
                    {
                        "labels": {
                            "result": "301",
                            "type": "inbound_message"
                        },
                        "value": 5
                    },
                    {
                        "labels": {
                            "result": "success",
                            "type": "inbound_message"
                        },
                        "value": 1
                    },
                    {
                        "labels": {
                            "result": "1",
                            "type": "status_change"
                        },
                        "value": 485
                    },
                    ...
                ],
                "help": "Total number of callback requests made",
                "type": "counter"
            },
            "endpoint_requests": {
                "data": [
                    {
                        "labels": {
                            "method": "contacts",
                            "result": "ok"
                        },
                        "value": 3864
                    },
                    {
                        "labels": {
                            "method": "messaging",
                            "result": "ok"
                        },
                        "value": 3576
                    },
                    {
                        "labels": {
                            "method": "messaging",
                            "result": "1020"
                        },
                        "value": 15
                    },
                    {
                        "labels": {
                            "method": "control",
                            "result": "ok"
                        },
                        "value": 4169
                    }
                ],
                "help": "Total number of endpoint requests made",
                "type": "counter"
            },
            "endpoint_requests_duration_ms": {
                "data": [
                    {
                        "bucket": {
                            "50": 237,
                            "500": 240,
                            "5000": 240
                        },
                        "count": 240,
                        "labels": {
                            "method": "support_info",
                            "result": "ok"
                        },
                        "sum": 1887
                    },
                    {
                        "bucket": {
                            "50": 128,
                            "500": 145,
                            "5000": 145
                        },
                        "count": 145,
                        "labels": {
                            "method": "send_document",
                            "result": "ok"
                        },
                        "sum": 3416
                    },
                    ...
                ],
                "help": "Duration(ms) of endpoint requests",
                "type": "histogram"
            },
            "in_message_decoded": {
                "data": [
                    {
                        "labels": {
                            "type": "image"
                        },
                        "value": 1
                    },
                    {
                        "labels": {
                            "type": "undefined"
                        },
                        "value": 8
                    }
                ],
                "help": "Total number of incoming messages",
                "type": "counter"
            },
            "in_message_from_server": {
                "data": [
                    {
                        "value": 9
                    }
                ],
                "help": "Total number of incoming encrypted messages from server",
                "type": "counter"
            },
            "in_message_persisted": {
                "data": [
                    {
                        "labels": {
                            "type": "image"
                        },
                        "value": 1
                    },
                    {
                        "labels": {
                            "type": "system"
                        },
                        "value": 3350
                    },
                    {
                        "labels": {
                            "type": "undefined"
                        },
                        "value": 8
                    }
                ],
                "help": "Total number of incoming messages cached in DB",
                "type": "counter"
            },
            "media_downloads": {
                "data": [
                    {
                        "labels": {
                            "result": "unknown",
                            "type": "image"
                        },
                        "value": 1
                    }
                ],
                "help": "Total number of media messages downloaded from server",
                "type": "counter"
            },
            "media_uploads": {
                "data": [
                    {
                        "labels": {
                            "result": "ok",
                            "type": "audio"
                        },
                        "value": 95
                    },
                    {
                        "labels": {
                            "result": "ok",
                            "type": "document"
                        },
                        "value": 145
                    },
                    {
                        "labels": {
                            "result": "ok",
                            "type": "image"
                        },
                        "value": 81
                    }
                ],
                "help": "Total number of media messages uploaded to server",
                "type": "counter"
            },
            "out_message_persisted": {
                "data": [
                    {
                        "labels": {
                            "type": "document"
                        },
                        "value": 145
                    },
                    {
                        "labels": {
                            "type": "audio"
                        },
                        "value": 95
                    },
                    {
                        "labels": {
                            "type": "image"
                        },
                        "value": 81
                    },
                    {
                        "labels": {
                            "type": "undefined"
                        },
                        "value": 79
                    },
                    {
                        "labels": {
                            "type": "hsm"
                        },
                        "value": 3176
                    }
                ],
                "help": "Total number of outgoing messages cached in DB",
                "type": "counter"
            },
            "out_message_received_by_server": {
                "data": [
                    {
                        "value": 2699
                    }
                ],
                "help": "Total number of outgoing messages received by server",
                "type": "counter"
            },
            "out_message_received_by_target": {
                "data": [
                    {
                        "value": 2
                    }
                ],
                "help": "Total number of outgoing messages received by target",
                "type": "counter"
            },
            "out_message_received_by_target_read": {
                "data": [
                    {
                        "value": 2
                    }
                ],
                "help": "Total number of outgoing messages read by target",
                "type": "counter"
            },
            "out_message_sent": {
                "data": [
                    {
                        "labels": {
                            "result": "success",
                            "type": "image"
                        },
                        "value": 81
                    },
                    {
                        "labels": {
                            "result": "success",
                            "type": "document"
                        },
                        "value": 145
                    },
                    {
                        "labels": {
                            "result": "success",
                            "type": "undefined"
                        },
                        "value": 79
                    },
                    {
                        "labels": {
                            "result": "success",
                            "type": "audio"
                        },
                        "value": 95
                    },
                    {
                        "labels": {
                            "result": "success",
                            "type": "hsm"
                        },
                        "value": 3176
                    }
                ],
                "help": "Total number of outgoing messages sent to server",
                "type": "counter"
            },
            "pending_callbacks": {
                "data": [
                    {
                        "labels": {
                            "type": "inbound_message"
                        },
                        "value": 8
                    },
                    {
                        "labels": {
                            "type": "status_change"
                        },
                        "value": 442
                    }
                ],
                "help": "Current number of pending callbacks in the queue",
                "type": "gauge"
            },
            "pending_messages": {
                "data": [
                    {
                        "value": 0
                    }
                ],
                "help": "Current number of pending messages in the queue",
                "type": "gauge"
            }
        }
    },
    "meta": {
        "api_status": "stable",
        "version": "2.21.1"
    }
}
  
  

Parameters

NameTypeDescription

callback_queue_size

Object

Current callback queue size

callback_requests*

Object

Total number of callback requests made and result

concurrent_rate_limit_triggered*

Object

Current number of concurrent rate limit triggers

endpoint_requests

Object

Total number of endpoint requests made for a given endpoint and result (either ok or an error code)

endpoint_requests_duration_ms

Object

Duration(in milliseconds) of endpoint requests

in_message_decoded*

Object

Total number of incoming messages decrypted successfully

in_message_from_server*

Object

Total number of incoming encrypted messages from server

in_message_persisted*

Object

Total number of incoming messages cached in the database

media_downloads*

Object

Total number of media files downloaded from server

media_uploads*

Object

Total number of media files uploaded to server

out_message_persisted*

Object

Total number of outgoing messages cached in the database

out_message_received_by_server*

Object

Total number of outgoing messages received by server

out_message_received_by_target*

Object

Total number of outgoing messages received by target

out_message_received_by_target_read*

Object

Total number of outgoing messages read by target

out_message_sent*

Object

Total number of outgoing messages sent to server

pending_callbacks*

Object

Current number of pending callbacks in the queue for each callback type

pending_messages

Object

Current number of pending messages in the queue

per_sec_request_rate_limit_triggered*

Object

Current number of per second request rate limit triggers

per_hour_request_rate_limit_triggered*

Object

Current number of per hour request rate limit triggers

per_day_request_rate_limit_triggered*

Object

Current number of per day request rate limit triggers

per_day_contacts_scrape_limit_triggered*

Object

Current number of per day contact scrape limit triggers

  • These response fields are available beginning with v2.21.3.

Coreapp Stats — Prometheus

Returns the Coreapp data in Prometheus format.

Request

GET /v1/stats/app?format=prometheus

Response

For example, the response might look like this:

# HELP callback_queue_size Current callback queue size
# TYPE callback_queue_size gauge
callback_queue_size 450
# HELP callback_requests Total number of callback requests made
# TYPE callback_requests counter
callback_requests{result="301",type="inbound_message"} 5
callback_requests{result="success",type="inbound_message"} 1
callback_requests{result="1",type="status_change"} 486
callback_requests{result="1",type="inbound_message"} 8
callback_requests{result="success",type="status_change"} 225
# HELP endpoint_requests Total number of endpoint requests made
# TYPE endpoint_requests counter
endpoint_requests{method="contacts",result="ok"} 3864
endpoint_requests{method="messaging",result="ok"} 3576
endpoint_requests{method="messaging",result="1020"} 15
endpoint_requests{method="control",result="ok"} 4262
# HELP endpoint_requests_duration_ms Duration(ms) of endpoint requests
# TYPE endpoint_requests_duration_ms histogram
endpoint_requests_duration_ms_bucket{method="support_info",result="ok",le="50"} 237
endpoint_requests_duration_ms_bucket{method="support_info",result="ok",le="500"} 240
endpoint_requests_duration_ms_bucket{method="support_info",result="ok",le="5000"} 240
...
# HELP in_message_decoded Total number of incoming messages
# TYPE in_message_decoded counter
in_message_decoded{type="image"} 1
in_message_decoded{type="undefined"} 8
# HELP in_message_from_server Total number of incoming encrypted messages from server
# TYPE in_message_from_server counter
in_message_from_server 9
# HELP in_message_persisted Total number of incoming messages cached in DB
# TYPE in_message_persisted counter
in_message_persisted{type="image"} 1
in_message_persisted{type="system"} 3350
in_message_persisted{type="undefined"} 8
# HELP media_downloads Total number of media messages downloaded from server
# TYPE media_downloads counter
media_downloads{result="unknown",type="image"} 1
# HELP media_uploads Total number of media messages uploaded to server
# TYPE media_uploads counter
media_uploads{result="ok",type="audio"} 95
media_uploads{result="ok",type="document"} 145
media_uploads{result="ok",type="image"} 81
# HELP out_message_persisted Total number of outgoing messages cached in DB
# TYPE out_message_persisted counter
out_message_persisted{type="document"} 145
out_message_persisted{type="audio"} 95
out_message_persisted{type="image"} 81
out_message_persisted{type="undefined"} 79
out_message_persisted{type="hsm"} 3176
# HELP out_message_received_by_server Total number of outgoing messages received by server
# TYPE out_message_received_by_server counter
out_message_received_by_server 2699
# HELP out_message_received_by_target Total number of outgoing messages received by target
# TYPE out_message_received_by_target counter
out_message_received_by_target 2
# HELP out_message_received_by_target_read Total number of outgoing messages read by target
# TYPE out_message_received_by_target_read counter
out_message_received_by_target_read 2
# HELP out_message_sent Total number of outgoing messages sent to server
# TYPE out_message_sent counter
out_message_sent{result="success",type="image"} 81
out_message_sent{result="success",type="document"} 145
out_message_sent{result="success",type="undefined"} 79
out_message_sent{result="success",type="audio"} 95
out_message_sent{result="success",type="hsm"} 3176
# HELP pending_callbacks Current number of pending callbacks in the queue
# TYPE pending_callbacks gauge
pending_callbacks{type="inbound_message"} 8
pending_callbacks{type="status_change"} 442
# HELP pending_messages Current number of pending messages in the queue
# TYPE pending_messages gauge
pending_messages 0

Database Stats

Use the /v1/stats/db endpoint to retrieve database stats in JSON format.

Checking the database stats can take a long time and affect app performance if your database is large. It is recommended polling this information only when needed.

Request

GET /v1/stats/db

Response

If successful, your request returns 200 OK and a message body containing an db object. For example, the complete response, including the db object, might look like this:

{
    "stats": {
        "db": {
            "db_contacts": {
                "data": [
                    {
                        "labels": {
                            "type": "non_whatsapp_user"
                        },
                        "value": 2
                    },
                    {
                        "labels": {
                            "type": "whatsapp_user"
                        },
                        "value": 5
                    }
                ],
                "help": "Current number of contacts in DB",
                "type": "gauge"
            },
            "db_message_receipts": {
                "data": [
                    {
                        "value": 6
                    }
                ],
                "help": "Current number of message receipts in DB",
                "type": "gauge"
            },
            "db_messages": {
                "data": [
                    {
                        "labels": {
                            "type": "undefined"
                        },
                        "value": 2
                    },
                    {
                        "labels": {
                            "type": "system"
                        },
                        "value": 1
                    }
                ],
                "help": "Current number of messages in DB",
                "type": "gauge"
            },
            "db_pending_callbacks": {
                "data": [
                    {
                        "value": 0
                    }
                ],
                "help": "Current number of pending callbacks in DB",
                "type": "gauge"
            },
            "db_pending_messages": {
                "data": [
                    {
                        "value": 0
                    }
                ],
                "help": "Current number of pending messages in DB",
                "type": "gauge"
            }
        }
    },
    "meta": {
        "api_status": "stable",
        "version": "2.18.13"
    }
} 
  

Parameters

NameTypeDescription

db_contacts

Object

Current number of contacts in the database

db_message_receipts

Object

Current number of message receipts in the database

db_messages

Object

Current number of messages in the database

db_pending_callbacks

Object

Current number of pending callbacks in the database

db_pending_messages

Object

Current number of pending messages in the database

Database Stats — Prometheus

Returns the database stats in Prometheus format.

Request

GET /v1/stats/db?format=prometheus

Response

For example, the response might look like this:

# HELP db_contacts Current number of contacts in DB
# TYPE db_contacts gauge
db_contacts{type="whatsapp_user"} 3
# HELP db_message_receipts Current number of message receipts in DB
# TYPE db_message_receipts gauge
db_message_receipts 0