diff options
Diffstat (limited to 'lib/diameter/doc')
| -rw-r--r-- | lib/diameter/doc/src/diameter.xml | 281 |
1 files changed, 277 insertions, 4 deletions
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.</p> <!-- ===================================================================== --> <func> -<name>service_info(SvcName, Item) -> Value</name> -<fsummary>Return specific information about a started service.</fsummary> +<name>service_info(SvcName, Item) -> term()</name> +<fsummary>Return information about a started service.</fsummary> <type> <v>SvcName = <seealso marker="#service_name">service_name()</seealso></v> -<v>Value = term()</v> </type> <desc> <p> -Return information about a started service.</p> +Return information about a started service. +<c>Item</c> can be one of the following.</p> + +<taglist> + +<tag><c>'Origin-Host'</c></tag> +<tag><c>'Origin-Realm'</c></tag> +<tag><c>'Vendor-Id'</c></tag> +<tag><c>'Product-Name'</c></tag> +<tag><c>'Origin-State-Id'</c></tag> +<tag><c>'Host-IP-Address'</c></tag> +<tag><c>'Supported-Vendor'</c></tag> +<tag><c>'Auth-Application-Id'</c></tag> +<tag><c>'Inband-Security-Id'</c></tag> +<tag><c>'Acct-Application-Id'</c></tag> +<tag><c>'Vendor-Specific-Application-Id'</c></tag> +<tag><c>'Firmware-Revision'</c></tag> +<item> +<p> +Return a capability value as configured on the service at <seealso +marker="#start_service">start_service/2</seealso>. +Note that all capabilities are returned in a tagged list with the +<c>capabilities</c> item.</p> +</item> + +<tag><c>applications</c></tag> +<item> +<p> +Return the list of applications configured on the service at <seealso +marker="#start_service">start_service/2</seealso>. +</p> +</item> + +<tag><c>capabilities</c></tag> +<item> +<p> +Return a tagged list of all capabilities values configured on the service +at <seealso +marker="#start_service">start_service/2</seealso>.</p> +</item> + +<tag><c>transport</c></tag> +<item> +<p> +Return a list containing one entry for every transport configured on +the service with <seealso +marker="#add_transport">add_transport/2</seealso>. +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.</p> + +<code> +[[{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}]}]] +</code> + +<p> +Here <c>ref</c> is the <seealso +marker="#transport_ref">transport_ref()</seealso> of the service's +transport and <c>options</c> are as were passed to <seealso +marker="#add_transport">add_transport/2</seealso>. +The <c>watchdog</c> entry shows the state of a connection's RFC 3539 watchdog +state machine. +The <c>peer</c> entry identifies the <seealso +marker="diameter_app#peer_ref">diameter_app:peer_ref()</seealso> for +which there will have been a <seealso +marker="diameter_app#peer_up">peer_up</seealso> callback for the +Diameter applications negotiated during capabilities exchange, which +are identified by the <c>apps</c> entry, <c>common</c> in this case +being the <seealso +marker="#application_alias">application_alias()</seealso> of this +application with Application Id 0. +The <c>caps</c> entry identifies the capabilities sent by the local +node and received from the peer during capabilities exchange. +The <c>port</c> entry displays socket-level information about the +transport connection. +The <c>statistics</c> entry presents Diameter-level counters, +an entry like <c>{{{0,280,1},recv},2}</c> saying that the client has +received 2 DWR messages: <c>{0,280,1} = {Application_Id, Command_Code, +R_Flag}</c>.</p> + +<p> +Note that <c>watchdog</c>, <c>peer</c>, <c>apps</c>, <c>caps</c> +and <c>port</c> entries depend on connectivity +with the peer and may not be present. +Note also that the <c>statistics</c> entry presents values acuumulated +during the lifetime of the transport configuration.</p> + +<p> +A listening transport presents its information slightly differently +since there may be multiple accepted connections for the same <seealso +marker="#transport_ref">transport_ref()</seealso>. +The <c>transport</c> info returned by a server with a single client +connection might look as follows.</p> + +<code> +[[{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}]}]] +</code> + +<p> +The information presented here is as in the <c>connect</c> case except +that the client connections are grouped under an <c>accept</c> tuple.</p> + +</item> + +<tag><c>connections</c></tag> +<item> +<p> +Return a list containing one entry for every established transport +connection whose watchdog state machine is not in the <c>down</c> +state. +This is a flat view of <c>transport</c> 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.</p> + +<code> +[[{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}]}]] +</code> + +<p> +Note that there may be multiple entries with the same <c>ref</c>, in +contrast to <c>transport</c> info.</p> +</item> + +<tag><c>statistics</c></tag> +<item> +<p> +Return a <c>{{Counter, Ref}, non_neg_integer()}</c> list of counter values. +<c>Ref</c> can be either a <seealso +marker="#transport_ref">transport_ref()</seealso> +or a <seealso +marker="diameter_app#peer_ref">diameter_app:peer_ref()</seealso>. +Entries for the latter are folded into corresponding entries for the +former as peer connections go down. +Entries for both are removed at <seealso +marker="#remove_transport">remove_transport/2</seealso>. +The Diameter-level statistics returned by <c>transport</c> and +<c>connections</c> info are based upon these entries.</p> +</item> + +</taglist> <marker id="services"/> </desc> |