From e72579c29bd86bb104f1855d6eebcf8677038f2f Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Tue, 28 Aug 2012 17:59:57 +0200 Subject: Document service info --- lib/diameter/doc/src/diameter.xml | 281 +++++++++++++++++++++++++++++++++++++- 1 file changed, 277 insertions(+), 4 deletions(-) (limited to 'lib/diameter/doc/src') diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 34203f737b..2abfbff209 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -1198,15 +1198,288 @@ DPA or timeout.

-service_info(SvcName, Item) -> Value -Return specific information about a started service. +service_info(SvcName, Item) -> term() +Return information about a started service. SvcName = service_name() -Value = term()

-Return information about a started service.

+Return information about a started service. +Item can be one of the following.

+ + + +'Origin-Host' +'Origin-Realm' +'Vendor-Id' +'Product-Name' +'Origin-State-Id' +'Host-IP-Address' +'Supported-Vendor' +'Auth-Application-Id' +'Inband-Security-Id' +'Acct-Application-Id' +'Vendor-Specific-Application-Id' +'Firmware-Revision' + +

+Return a capability value as configured on the service at start_service/2. +Note that all capabilities are returned in a tagged list with the +capabilities item.

+ + +applications + +

+Return the list of applications configured on the service at start_service/2. +

+ + +capabilities + +

+Return a tagged list of all capabilities values configured on the service +at start_service/2.

+ + +transport + +

+Return a list containing one entry for every transport configured on +the service with add_transport/2. +Each entry is a tagged list containing both configuration and +information about established peer connections. +An example return value with for a client service with Origin-Host +"client.example.com" configured with a single transport connected to "server.example.com" +might look as follows.

+ + +[[{ref,#Ref<0.0.0.93>}, + {type,connect}, + {options,[{transport_module,diameter_tcp}, + {transport_config,[{ip,{127,0,0,1}}, + {raddr,{127,0,0,1}}, + {rport,3868}, + {reuseaddr,true}]}]}, + {watchdog,{<0.66.0>,{1346,171491,996448},okay}}, + {peer,{<0.67.0>,{1346,171491,999906}}}, + {apps,[{0,common}]}, + {caps,[{origin_host,{"client.example.com","server.example.com"}}, + {origin_realm,{"example.com","example.com"}}, + {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}}, + {vendor_id,{0,193}}, + {product_name,{"Client","Server"}}, + {origin_state_id,{[],[]}}, + {supported_vendor_id,{[],[]}}, + {auth_application_id,{[0],[0]}}, + {inband_security_id,{[],[0]}}, + {acct_application_id,{[],[]}}, + {vendor_specific_application_id,{[],[]}}, + {firmware_revision,{[],[]}}, + {avp,{[],[]}}]}, + {port,[{owner,<0.69.0>}, + {module,diameter_tcp}, + {socket,{{127,0,0,1},48758}}, + {peer,{{127,0,0,1},3868}}, + {statistics,[{recv_oct,656}, + {recv_cnt,6}, + {recv_max,148}, + {recv_avg,109}, + {recv_dvi,19}, + {send_oct,836}, + {send_cnt,6}, + {send_max,184}, + {send_avg,139}, + {send_pend,0}]}]}, + {statistics,[{{{0,258,0},recv},3}, + {{{0,258,1},send},3}, + {{{0,257,0},recv},1}, + {{{0,257,1},send},1}, + {{{0,258,0},recv,{'Result-Code',2001}},3}, + {{{0,280,1},recv},2}, + {{{0,280,0},send},2}]}]] + + +

+Here ref is the transport_ref() of the service's +transport and options are as were passed to add_transport/2. +The watchdog entry shows the state of a connection's RFC 3539 watchdog +state machine. +The peer entry identifies the diameter_app:peer_ref() for +which there will have been a peer_up callback for the +Diameter applications negotiated during capabilities exchange, which +are identified by the apps entry, common in this case +being the application_alias() of this +application with Application Id 0. +The caps entry identifies the capabilities sent by the local +node and received from the peer during capabilities exchange. +The port entry displays socket-level information about the +transport connection. +The statistics entry presents Diameter-level counters, +an entry like {{{0,280,1},recv},2} saying that the client has +received 2 DWR messages: {0,280,1} = {Application_Id, Command_Code, +R_Flag}.

+ +

+Note that watchdog, peer, apps, caps +and port entries depend on connectivity +with the peer and may not be present. +Note also that the statistics entry presents values acuumulated +during the lifetime of the transport configuration.

+ +

+A listening transport presents its information slightly differently +since there may be multiple accepted connections for the same transport_ref(). +The transport info returned by a server with a single client +connection might look as follows.

+ + +[[{ref,#Ref<0.0.0.61>}, + {type,listen}, + {options,[{transport_module,diameter_tcp}, + {transport_config,[{reuseaddr,true}, + {ip,{127,0,0,1}}, + {port,3868}]}]}, + {accept,[[{watchdog,{<0.56.0>,{1346,171481,226895},okay}}, + {peer,{<0.58.0>,{1346,171491,999511}}}, + {apps,[{0,server}]}, + {caps,[{origin_host,{"server.example.com","client.example.com"}}, + {origin_realm,{"example.com","example.com"}}, + {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}}, + {vendor_id,{193,0}}, + {product_name,{"Server","Client"}}, + {origin_state_id,{[],[]}}, + {supported_vendor_id,{[],[]}}, + {auth_application_id,{[0],[0]}}, + {inband_security_id,{[],[]}}, + {acct_application_id,{[],[]}}, + {vendor_specific_application_id,{[],[]}}, + {firmware_revision,{[],[]}}, + {avp,{[],[]}}]}, + {port,[{owner,<0.62.0>}, + {module,diameter_tcp}, + {socket,{{127,0,0,1},3868}}, + {peer,{{127,0,0,1},48758}}, + {statistics,[{recv_oct,1576}, + {recv_cnt,16}, + {recv_max,184}, + {recv_avg,98}, + {recv_dvi,26}, + {send_oct,1396}, + {send_cnt,16}, + {send_max,148}, + {send_avg,87}, + {send_pend,0}]}]}], + [{watchdog,{<0.72.0>,{1346,171491,998404},initial}}]]}, + {statistics,[{{{0,280,0},recv},7}, + {{{0,280,1},send},7}, + {{{0,258,0},send,{'Result-Code',2001}},3}, + {{{0,258,1},recv},3}, + {{{0,258,0},send},3}, + {{{0,280,1},recv},5}, + {{{0,280,0},send},5}, + {{{0,257,1},recv},1}, + {{{0,257,0},send},1}]}]] + + +

+The information presented here is as in the connect case except +that the client connections are grouped under an accept tuple.

+ + + +connections + +

+Return a list containing one entry for every established transport +connection whose watchdog state machine is not in the down +state. +This is a flat view of transport info which lists only active +connections and for which Diameter-level statistics are accumulated +only for the lifetime of the transport connection. +A return value for the server above might look as follows.

+ + +[[{ref,#Ref<0.0.0.61>}, + {type,accept}, + {options,[{transport_module,diameter_tcp}, + {transport_config,[{reuseaddr,true}, + {ip,{127,0,0,1}}, + {port,3868}]}]}, + {watchdog,{<0.56.0>,{1346,171481,226895},okay}}, + {peer,{<0.58.0>,{1346,171491,999511}}}, + {apps,[{0,server}]}, + {caps,[{origin_host,{"server.example.com","client.example.com"}}, + {origin_realm,{"example.com","example.com"}}, + {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}}, + {vendor_id,{193,0}}, + {product_name,{"Server","Client"}}, + {origin_state_id,{[],[]}}, + {supported_vendor_id,{[],[]}}, + {auth_application_id,{[0],[0]}}, + {inband_security_id,{[],[]}}, + {acct_application_id,{[],[]}}, + {vendor_specific_application_id,{[],[]}}, + {firmware_revision,{[],[]}}, + {avp,{[],[]}}]}, + {port,[{owner,<0.62.0>}, + {module,diameter_tcp}, + {socket,{{127,0,0,1},3868}}, + {peer,{{127,0,0,1},48758}}, + {statistics,[{recv_oct,10124}, + {recv_cnt,132}, + {recv_max,184}, + {recv_avg,76}, + {recv_dvi,9}, + {send_oct,10016}, + {send_cnt,132}, + {send_max,148}, + {send_avg,75}, + {send_pend,0}]}]}, + {statistics,[{{{0,280,0},recv},62}, + {{{0,280,1},send},62}, + {{{0,258,0},send,{'Result-Code',2001}},3}, + {{{0,258,1},recv},3}, + {{{0,258,0},send},3}, + {{{0,280,1},recv},66}, + {{{0,280,0},send},66}, + {{{0,257,1},recv},1}, + {{{0,257,0},send},1}]}]] + + +

+Note that there may be multiple entries with the same ref, in +contrast to transport info.

+ + +statistics + +

+Return a {{Counter, Ref}, non_neg_integer()} list of counter values. +Ref can be either a transport_ref() +or a diameter_app:peer_ref(). +Entries for the latter are folded into corresponding entries for the +former as peer connections go down. +Entries for both are removed at remove_transport/2. +The Diameter-level statistics returned by transport and +connections info are based upon these entries.

+ + + -- cgit v1.2.3