...

Package metrics

import "github.com/Diarkis/diarkis/metrics"
Overview
Index

Overview ▾

Package metrics ▷

Metrics

Allows you to extend built-in metrics data with your own custom metrics names and values.

Configurations

Metrics package has optional configurations for adding customized metrics from your application.

{
  "names": [ $(name) ... ]
}

Configuration properties

name - A list of custom metrics names to be used.
       Each name must have value update function assigned.

Custom Metrics Example

In order to add your own custom metrics, you must have a configuration JSON file and have HTTP and your other server (TCP/UDP) read it.

The example shown below will explain how it is done:

HTTP servers must load the configuration file containing the names of custom metrics.

// You must call metrics.Setup() before calling diarkis.Start()
metrics.Setup("/absolute/path/to/my/config/JSON/file")

The custom metrics names must match the parameters given to metrics.DefineMetricsValue in the network servers (UDP and/or TCP and/or custom type servers).

Network Server (UDP and/or TCP and/or custom type servers) Example

UDP and/or TCP and/or custom type server must also load the configuration file containing the names of custom metrics. Additionally, the server must also need to define how the values of custom metrics should be counted as shown as an example below:

// You must call metrics.Setup() before calling diarkis.Start()
// You also must call metrics.Setup after calling mesh.Setup(...)
metrics.Setup("/absolute/path/to/my/config/JSON/file")

// Make sure the name used here is configured in the config JSON file: "names": [ "MyCustomMetrics" ]
customMetricsName := "MyCustomMetrics"

// You must call metrics.Setup() before calling diarkis.Start()
// You also must call metrics.Setup after calling mesh.Setup(...)
// The callback function assigned here will be invoked at every mesh package update
metrics.DefineMetricsValue(customMetricsName, func() int {

  // returned value will be your custom metrics value
  return customMetricsValue

})

Built-in Metrics

Diarkis has built-in metrics that you may use out-of-the-box. This section will explain each built-in metrics.

$(server_type) is a variable that depends on what server types you have in your Diarkis server cluster.

▶︎ CCU Count

Users_$(server_type)_node

CCU (Concurrent Users) per server (node). This number represents the currently connected and active client devices per server.

▶︎ Room Count

Rooms_$(server_type)_node

Represents how many rooms exists on a server (node).

▶︎ Group Count

Groups_$(server_type)_node

Represents how many groups exists on a server (node). Since Diarkis Group is distributed through out the entire Diarkis server cluster, the number of groups may be redundant across multiple servers. It means that multiple count of groups on multiple servers may represents a single group.

▶︎ Inbound Packet Count

UDP_Packets_In_$(server_type)_node

Represents the number of received inbound UDP packets on a server (node).

▶︎ Outbound Packet Count

UDP_Packets_Out_$(server_type)_node

Represents the number of outbound UDP packets sent from a server (node).

▶︎ Inbound Command Count

Commands_In_$(server_type)_node

Represents the number of received inbound commands on a server (node). A single packet may contain multiple commands.

▶︎ Outbound Command Count

Commands_Out_$(server_type)_node

Represents the number of outbound commands sent from a server (node). A single packet may contain multiple commands.

▶︎ Outbound RUDP Retry Packet Count

RUDP_Retries_$(server_type)_node

Represents the number of outbound RUDP retry packets sent from a server (node).

▶︎ Inbound RUDP Split Packet Count

RUDP_Split_In_$(server_type)_node

Represents the number of received inbound RUDP split packets on a server (node). When the client sent a RUDP packet that exceeds MTU, Diarkis automatically split the packet into smaller packets and send them separately.

▶︎ Outbound RUDP Split Packet Count

RUDP_Split_Out_$(server_type)_node

Represents the number of outbound RUDP split packets sent from a server (node). When the client sent a RUDP packet that exceeds MTU, Diarkis automatically split the packet into smaller packets and send them separately.

▶︎ Inbound Internal Packet Count

Mesh_Packets_In_($server_type)_node

Represents the number of received inbound internal packets on a server (node). Every Diarkis server is able to send and receive packets internally.

▶︎ Outbound Internal Packet Count

Mesh_Packets_Out_$(server_type)_node

Represents the number of outbound packets sent from a server (node). Every Diarkis server is able to send and receive packets internally.

▶︎ Outbound Internal Retry Packet Count

Mesh_Retry_$(server_type)_node

Represents the number of outbound retried internal packets sent from a server (node). Every Diarkis server is able to send and receive packets internally. Increase of this number usually indicates the increase of server workload.

▶︎ MatchMaker Internal Search Count

MatchMaker_Search_$(server_type)_node

Represents the number of executed matchmaking internal searches. A single MatchMaker search may execute multiple internal searches.

▶︎ MatchMaker Internal Empty Search Result Count

MatchMaker_Empty_$(server_type)_node

Represents the number of empty internal search results. A single MatchMaker search may execute multiple internal searches.

▶︎ MatchMaker Issued Ticket Count

MatchMaker_Ticket_$(server_type)_node

Represents the number of issued MatchMaker Tickets.

▶︎ MatchMaker Ticket Search Count

MatchMaker_Ticket_Search_$(server_type)_node

Represents the number of ticket searches executed. Ticket searches target waiting tickets.

▶︎ MatchMaker Ticket Add (Wait) Count

MatchMaker_Ticket_Add_$(server_type)_node

Represents the number of waiting tickets. Waiting tickets are to be searched and found by ticket searches.

▶︎ MatchMaker Ticket Successful Completion Count

MatchMaker_Complete_UDP_node

Represents the number of successfully completed tickets.

▶︎ MatchMaker Ticket Completion Average Time

MatchMaker_Ticket_Complete_Time_Avg_$(server_type)_node

Represents the average time a ticket takes to successfully complete in seconds.

▶︎ MatchMaker Ticket Completion Minimum Time

MatchMaker_Ticket_Complete_Time_Min_$(server_type)_node

Represents the minimum time a ticket takes to successfully complete in seconds.

▶︎ MatchMaker Ticket Completion Maximum Time

MatchMaker_Ticket_Complete_Time_Max_$(server_type)_node

Represents the maximum time a ticket takes to successfully complete in seconds.

▶︎ P2P Success Count

P2P_Success_$(server_type)_node

Represents the number of successful peer-to-peer hole punchings.

▶︎ P2P Attempt Count

P2P_Attempt_$(server_type)_node

Represents the number of peer-to-peer attempts by the client.

Constants

FieldGridName used in field

const FieldGridName = "Field_Grids"

FieldMeshGridCntName

const FieldMeshGridCntName = "fg"

GroupMeshVaultName used in group

const GroupMeshVaultName = "g"

GroupVaultName used in group

const GroupVaultName = "Groups"

MatchMakerCompleteCnt used in matching

const MatchMakerCompleteCnt = "mc"

MatchMakerCompleteName used in matching

const MatchMakerCompleteName = "MatchMaker_Complete"

MatchMakerEmptySearchCnt used in matching

const MatchMakerEmptySearchCnt = "me"

MatchMakerEmptySearchname used in matching

const MatchMakerEmptySearchName = "MatchMaker_Empty"

MatchMakerSearchCnt used in matching

const MatchMakerSearchCnt = "ms"

MatchMakerSearchName used in matching

const MatchMakerSearchName = "MatchMaker_Search"
const MatchMakerTicketAddCnt = "mta"
const MatchMakerTicketAddName = "MatchMaker_Ticket_Add"
const MatchMakerTicketCnt = "mt"
const MatchMakerTicketCompleteTimeAvg = "mtt"
const MatchMakerTicketCompleteTimeAvgName = "MatchMaker_Ticket_Complete_Time_Avg"
const MatchMakerTicketCompleteTimeMax = "mtx"
const MatchMakerTicketCompleteTimeMaxName = "MatchMaker_Ticket_Complete_Time_Max"
const MatchMakerTicketCompleteTimeMin = "mtn"
const MatchMakerTicketCompleteTimeMinName = "MatchMaker_Ticket_Complete_Time_Min"
const MatchMakerTicketName = "MatchMaker_Ticket"
const MatchMakerTicketSearchCnt = "mts"
const MatchMakerTicketSearchName = "MatchMaker_Ticket_Search"

MeshPktSampleIn used in mesh

const MeshPktSampleIn = "mi"

MeshPktSampleInName used in mesh

const MeshPktSampleInName = "Mesh_Packets_In"

MeshPktSampleOut used in mesh

const MeshPktSampleOut = "mo"

MeshPktSampleOutName used in mesh

const MeshPktSampleOutName = "Mesh_Packets_Out"

MeshPktSampleRetry used in mesh

const MeshPktSampleRetry = "mr"

MeshPktSampleRetryName used in mesh

const MeshPktSampleRetryName = "Mesh_Retry"

P2PAttemptCnt used in P2P

const P2PAttemptCnt = "pa"

P2PAttemptName used in P2P attempt count report

const P2PAttemptName = "P2P_Attempt"

P2PSuccess used in P2P success count report

const P2PSuccessCnt = "ps"

P2PSuccessName used in P2P success count report

const P2PSuccessName = "P2P_Success"

RoomMeshVaultName used in room

const RoomMeshVaultName = "r"

RoomVaultName used in room

const RoomVaultName = "Rooms"

TCPPktSampleIn used in tcp

const TCPPktSampleIn = "ti"

TCPPktSampleInName used in tcp

const TCPPktSampleInName = "TCP_Packets_In"

TCPPktSampleOut used in tcp

const TCPPktSampleOut = "to"

TCPPktSampleOutName used in tcp

const TCPPktSampleOutName = "TCP_Packets_Out"

UDPCmdSample used in udp

const UDPCmdSample = "um"

UDPCmdSampleName used in udp

const UDPCmdSampleName = "Commands_In"

UDPPktSampleIn used in udp

const UDPPktSampleIn = "ui"

UDPPktSampleInName used in udp

const UDPPktSampleInName = "UDP_Packets_In"

UDPPktSampleOut used in udp

const UDPPktSampleOut = "uo"

UDPPktSampleOutName used in udp

const UDPPktSampleOutName = "UDP_Packets_Out"

UDPRetrySample used in udp

const UDPRetrySample = "ur"

UDPRetrySampleName used in udp

const UDPRetrySampleName = "RUDP_Retries"

UDPSendSample used in udp

const UDPSendSample = "us"

UDPSendSampleName used in udp

const UDPSendSampleName = "Commands_Out"

UDPSplitSampleIn used in udp

const UDPSplitSampleIn = "si"

UDPSplitSampleInName used in udp

const UDPSplitSampleInName = "RUDP_Split_In"

UDPSplitSampleOut used in udp

const UDPSplitSampleOut = "so"

UDPSplitSampleOutName used in udp

const UDPSplitSampleOutName = "RUDP_Split_Out"

MeshVaultName used in user

const UserMeshVaultName = "uc"

VaultName used in user

const UserVaultName = "Users"

func DefineMetricsValue

func DefineMetricsValue(name string, cb ValueUpdate) error

DefineMetricsValue defines the value update operation of the metrics name given.

[IMPORTANT] MUST invoke this function BEFORE calling diarkis.Start()
[IMPORTANT] MUST invoke this function AFTER calling mesh.Setup(...)

Error Cases

┌────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────┐
│ Error                                          │ Reason                                                                       │
├────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────┤
│ Setup must invoked at the start of the process │ Invoking this function without calling Setup() is not allowed.               │
│ Must be invoked BEFORE the start of Diarkis    │ Invoking this function after the start of Diarkis is not allowed.            │
│ Metrics name must be configured                │ All metrics names must be configured in the configuration file.              │
│ Metrics value update function already assigned │ Assigning multiple value update functions for a metrics name is not allowed. │
└────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────┘

The name must be configured in a configuration file.

func GetMetricsValues

func GetMetricsValues(nodeType string) map[string][]*Item

GetMetricsValues [INTERNAL USE ONLY] returns all metrics values with the configured names and update functions

func PassMeshGetNodeAddressesByRole

func PassMeshGetNodeAddressesByRole(cb func(string) []string)

PassMeshGetNodeAddressesByRole [INTERNAL USE ONLY]

func PassMeshGetNodeTypeByAddress

func PassMeshGetNodeTypeByAddress(cb func(string) string)

PassMeshGetNodeTypeByAddress [INTERNAL USE ONLY]

func PassMeshGetNodeValue

func PassMeshGetNodeValue(cb func(string, string) interface{})

PassMeshGetNodeValue [INTERNAL USE ONLY]

func PassMeshOnUpdate

func PassMeshOnUpdate(cb func(func()))

PassMeshOnUpdate [INTERNAL USE ONLY]

func PassMeshSetNodeValue

func PassMeshSetNodeValue(cb func(string, interface{}))

PassMeshSetNodeValue [INTERNAL USE ONLY]

func Setup

func Setup(path string)

Setup must be invoked at the start of the process in order to use metrics.

[IMPORTANT] Must invoke this function BEFORE calling diarkis.Start()
[IMPORTANT] MUST invoke this function AFTER calling mesh.Setup(...)

type Item

Item [INTERNAL USE ONLY] represents a metrics value

type Item struct {
    Addr  string
    Value interface{}
    Type  string
}

type ValueUpdate

ValueUpdate is a function that updates the associated metrics value by using the returned value as its associated metrics value.

type ValueUpdate func() (value int)