commit 6f2919a2ede935b8783e1fa93178ebb425b54f17 Author: Karsten Loesing karsten.loesing@gmx.net Date: Thu Oct 31 09:13:39 2013 +0100

Merge implemented proposal 218 into control-spec.txt. --- control-spec.txt | 152 ++++++++++++++++++++++++++++- proposals/218-usage-controller-events.txt | 4 +- 2 files changed, 153 insertions(+), 3 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt index beb6593..f84d078 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -183,6 +183,8 @@ ; uses digits, but this may change StreamID = 1*16 IDChar CircuitID = 1*16 IDChar + ConnID = 1*16 IDChar + QueueID = 1*16 IDChar IDChar = ALPHA / DIGIT

Address = ip4-address / ip6-address / hostname (XXXX Define these) @@ -1496,7 +1498,7 @@ The syntax is:

"650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON=" - Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF + Reason ] [ SP "NCIRCS=" NumCircuits ] [ SP "ID=" ConnID ] CRLF

ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED"

@@ -1553,6 +1555,7 @@ descriptors, buffers, etc) to connect to the OR. MISC -- The OR connection closed for some other reason.

+ [First added ID parameter in 0.2.5.2-alpha]

4.1.4. Bandwidth used in the last second

@@ -2270,6 +2273,153 @@ A pluggable transport called 'Name' of type 'Type' was launched successfully and is now listening for connections on 'Address':'Port'.

+4.1.21. Bandwidth used on an OR or DIR or EXIT connection + + The syntax is: + "650" SP "CONN_BW" SP "ID=" ConnID SP "TYPE=" ConnType + SP "READ=" BytesRead SP "WRITTEN=" BytesWritten CRLF + ConnType = "OR" / "DIR" / "EXIT" + BytesRead = 1*DIGIT + BytesWritten = 1*DIGIT + + Controllers MUST tolerate unrecognized connection types. + + BytesWritten and BytesRead are the number of bytes written and read + by Tor since the last CONN_BW event on this connection. + + These events are generated about once per second per connection; no + events are generated for connections that have not read or written. + These events are only generated if TestingTorNetwork is set. + + [First added in 0.2.5.2-alpha] + +4.1.22. Bandwidth used by all streams attached to a circuit + + The syntax is: + "650" SP "CIRC_BW" SP "ID=" CircuitID SP "READ=" BytesRead SP + "WRITTEN=" BytesWritten CRLF + BytesRead = 1*DIGIT + BytesWritten = 1*DIGIT + + BytesRead and BytesWritten are the number of bytes read and written by + all applications with streams attached to this circuit since the last + CIRC_BW event. + + These events are generated about once per second per circuit; no events + are generated for circuits that had no attached stream writing or + reading. + + [First added in 0.2.5.2-alpha] + +4.1.23. Per-circuit cell stats + + The syntax is: + "650" SP "CELL_STATS" + [ SP "ID=" CircuitID ] + [ SP "InboundQueue=" QueueID SP "InboundConn=" ConnID ] + [ SP "InboundAdded=" CellsByType ] + [ SP "InboundRemoved=" CellsByType SP + "InboundTime=" MsecByType ] + [ SP "OutboundQueue=" QueueID SP "OutboundConn=" ConnID ] + [ SP "OutboundAdded=" CellsByType ] + [ SP "OutboundRemoved=" CellsByType SP + "OutboundTime=" MsecByType ] CRLF + CellsByType, MsecByType = CellType ":" 1*DIGIT + 0*( "," CellType ":" 1*DIGIT ) + CellType = 1*( "a" - "z" / "0" - "9" / "_" ) + + Examples are: + 650 CELL_STATS ID=14 OutboundQueue=19403 OutboundConn=15 + OutboundAdded=create_fast:1,relay_early:2 + OutboundRemoved=create_fast:1,relay_early:2 + OutboundTime=create_fast:0,relay_early:0 + 650 CELL_STATS InboundQueue=19403 InboundConn=32 + InboundAdded=relay:1,created_fast:1 + InboundRemoved=relay:1,created_fast:1 + InboundTime=relay:0,created_fast:0 + OutboundQueue=6710 OutboundConn=18 + OutboundAdded=create:1,relay_early:1 + OutboundRemoved=create:1,relay_early:1 + OutboundTime=create:0,relay_early:0 + + ID is the locally unique circuit identifier that is only included if the + circuit originates at this node. + + Inbound and outbound refer to the direction of cell flow through the + circuit which is either to origin (inbound) or from origin (outbound). + + InboundQueue and OutboundQueue are identifiers of the inbound and + outbound circuit queues of this circuit. These identifiers are only + unique per OR connection. OutboundQueue is chosen by this node and + matches InboundQueue of the next node in the circuit. + + InboundConn and OutboundConn are locally unique IDs of inbound and + outbound OR connection. OutboundConn does not necessarily match + InboundConn of the next node in the circuit. + + InboundQueue and InboundConn are not present if the circuit originates + at this node. OutboundQueue and OutboundConn are not present if the + circuit (currently) ends at this node. + + InboundAdded and OutboundAdded are total number of cells by cell type + added to inbound and outbound queues. Only present if at least one cell + was added to a queue. + + InboundRemoved and OutboundRemoved are total number of cells by + cell type processed from inbound and outbound queues. InboundTime and + OutboundTime are total waiting times in milliseconds of all processed + cells by cell type. Only present if at least one cell was removed from + a queue. + + These events are generated about once per second per circuit; no + events are generated for circuits that have not added or processed any + cell. These events are only generated if TestingTorNetwork is set. + + [First added in 0.2.5.2-alpha] + +4.1.24. Token buckets refilled + + The syntax is: + "650" SP "TB_EMPTY" SP BucketName [ SP "ID=" ConnID ] SP + "READ=" ReadBucketEmpty SP "WRITTEN=" WriteBucketEmpty SP + "LAST=" LastRefill CRLF + + BucketName = "GLOBAL" / "RELAY" / "ORCONN" + ReadBucketEmpty = 1*DIGIT + WriteBucketEmpty = 1*DIGIT + LastRefill = 1*DIGIT + + Examples are: + 650 TB_EMPTY ORCONN ID=16 READ=0 WRITTEN=0 LAST=100 + 650 TB_EMPTY GLOBAL READ=93 WRITTEN=93 LAST=100 + 650 TB_EMPTY RELAY READ=93 WRITTEN=93 LAST=100 + + This event is generated when refilling a previously empty token + bucket. BucketNames "GLOBAL" and "RELAY" keywords are used for the + global or relay token buckets, BucketName "ORCONN" is used for the + token buckets of an OR connection. Controllers MUST tolerate + unrecognized bucket names. + + ConnID is only included if the BucketName is "ORCONN". + + If both global and relay buckets and/or the buckets of one or more OR + connections run out of tokens at the same time, multiple separate + events are generated. + + ReadBucketEmpty (WriteBucketEmpty) is the time in millis that the read + (write) bucket was empty since the last refill. LastRefill is the + time in millis since the last refill. + + If a bucket went negative and if refilling tokens didn't make it go + positive again, there will be multiple consecutive TB_EMPTY events for + each refill interval during which the bucket contained zero tokens or + less. In such a case, ReadBucketEmpty or WriteBucketEmpty are capped + at LastRefill in order not to report empty times more than once. + + These events are only generated if TestingTorNetwork is set. + + [First added in 0.2.5.2-alpha] + 5. Implementation notes

5.1. Authentication diff --git a/proposals/218-usage-controller-events.txt b/proposals/218-usage-controller-events.txt index 34d14b3..76c64cd 100644 --- a/proposals/218-usage-controller-events.txt +++ b/proposals/218-usage-controller-events.txt @@ -2,8 +2,8 @@ Filename: 218-usage-controller-events.txt Title: Controller events to better understand connection/circuit usage Author: Rob Jansen, Karsten Loesing Created: 2013-02-06 -Status: Open -Target: 0.2.5.x +Status: Closed +Implemented-In: 0.2.5.2-alpha

1. Overview