aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAnders Svensson <[email protected]>2012-08-28 17:59:57 +0200
committerAnders Svensson <[email protected]>2012-08-29 18:22:22 +0200
commite72579c29bd86bb104f1855d6eebcf8677038f2f (patch)
tree742bde86e6d0102d3c8f5bf48b0c29fa16f35bc1
parentbec7d6a34b795a8e5725c86bd6465bedd8deb0b5 (diff)
downloadotp-e72579c29bd86bb104f1855d6eebcf8677038f2f.tar.gz
otp-e72579c29bd86bb104f1855d6eebcf8677038f2f.tar.bz2
otp-e72579c29bd86bb104f1855d6eebcf8677038f2f.zip
Document service info
-rw-r--r--lib/diameter/doc/src/diameter.xml281
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&lt;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,{&lt;0.66.0>,{1346,171491,996448},okay}},
+ {peer,{&lt;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,&lt;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&lt;0.0.0.61>},
+ {type,listen},
+ {options,[{transport_module,diameter_tcp},
+ {transport_config,[{reuseaddr,true},
+ {ip,{127,0,0,1}},
+ {port,3868}]}]},
+ {accept,[[{watchdog,{&lt;0.56.0>,{1346,171481,226895},okay}},
+ {peer,{&lt;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,&lt;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,{&lt;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&lt;0.0.0.61>},
+ {type,accept},
+ {options,[{transport_module,diameter_tcp},
+ {transport_config,[{reuseaddr,true},
+ {ip,{127,0,0,1}},
+ {port,3868}]}]},
+ {watchdog,{&lt;0.56.0>,{1346,171481,226895},okay}},
+ {peer,{&lt;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,&lt;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>