[jwrosewell]

.NET is the model for usage sharing. This specification now describes what .NET's usage sharing builder and element do with sessions and lists every option the .NET builder has. It also makes a back-off after failed sends a requirement for every usage sharing element, and makes the repeat Evidence interval a sliding window that every language follows.

Problem

1. The configuration options of the usage sharing element had no session tracking option and no session cookie name, and the session tracking section only described not sending repeated Evidence. .NET has both settings.
2. .NET has five recovery settings that the table did not list, and they do nothing. pipeline-dotnet#261 took the back-off out of usage sharing in February 2026 and left the five setters. The back-off it removed, from pipeline-dotnet#218, stopped processing as well as sending, and sends were only started by processing, so the queue never drained and users with many requests lost most of their usage data. With no back-off at all, every message is sent and lost while the service is failing. Java, Python and Node have never had one.
3. The session tracking section said an entry's lifetime "is reset each time an entry with matching Evidence values is processed", and the table called the interval a sliding window. In .NET, TrackerBase.Track (lines 114 to 132) stores a time only for a new entry, and ShareUsageTracker.Match (lines 98 to 107) never moves it on, so a repeat is held back for the interval after it was first shared and then shared on every request until the entry leaves the cache. Java does the same (ShareUsageTracker.java). Python and Node store a new time when they share a repeat, so they share it at most once in each interval. None of them resets the time on every match, which would stop Evidence seen continuously from ever being shared again.

.NET, the reference

All links are to 51degrees-dotnet at rc commit f0fb06e.

• SetTrackSession(bool), in ShareUsageBuilderBase.cs lines 543 to 560, says "If set to true, the configured session cookie will be used to identify user sessions. This will help to differentiate duplicate values that should not be shared." Its default is SHARE_USAGE_DEFAULT_TRACK_SESSION = false (Engines.FiftyOne/Constants.cs lines 88 to 95).
• SetAspSessionCookieName(string), in lines 514 to 527, says "This setting has no effect if TrackSession is false." Its default is DEFAULT_ASP_COOKIE_NAME = "asp.net_sessionid" (Engines/Constants.cs lines 49 to 53).
• ShareUsageBase.cs lines 636 to 666 builds three filters. The one for the Evidence the element accepts includes the session cookie, the one for what is shared leaves it out, and the tracker's includes it only when trackSession is true. When all Evidence is shared, all three accept every cookie and the session setting is not used. The cookie rule is in EvidenceKeyFilterShareUsage.cs lines 264 to 272.
• ShareUsageTrackerTests.cs lines 133 to 207 show the result. With the session cookie compared, the same Evidence from two sessions is tracked twice (ShareUsageTracker_Session_Track), and without it once (ShareUsageTracker_Session_DoNotTrack).
• The maximum queue size, in ShareUsageBuilderBase.cs lines 68 to 92, defaults to 1000, or ten times the minimum entries per message if that is larger.
• The five recovery setters are in lines 562 to 640, with their defaults in Engines.FiftyOne/Constants.cs lines 109 to 157. 51degrees-dotnet#88 makes them work again, as the new section below describes.

Change

1. Configuration options lists Track session, false by default, and Session cookie name, asp.net_sessionid in .NET, which has no effect unless track session is on.
2. Session tracking says how the session cookie is used. By default it is not compared, so identical Evidence matches the same entry whichever session it comes from. With track session on it is compared, so a repeat from a new session is shared and a repeat within the same session is not. The session cookie itself is not shared. When all Evidence is shared, every cookie is shared and compared, so track session has no effect, as in .NET.
3. Accepted Evidence says the session cookie is the one exception to the cookie rule. The filter MAY accept it, MUST accept it when session tracking is on so that the tracker can read it, and MUST NOT share it unless all Evidence is shared. It says MAY because .NET's filter accepts the session cookie whether or not tracking is on, while Python and Node accept it only when tracking is on. None of them shares it, and none compares it unless tracking is on, so what reaches 51Degrees is the same.
4. The Maximum queue size default changes from 1000 to .NET's "1000, or ten times the minimum entries per message if that is larger". This changes behaviour the specification already defined, because .NET differs.
5. A new section, Back-off after failed sends, makes the back-off a requirement. Repeated failed sends pause sending, never processing. A send fails when it cannot be made, has no answer in time, or is answered with anything other than 200. After the failures to enter recovery number of failed sends within the failures window, sending pauses for the initial recovery delay. The first send after a pause is a trial, and if it fails the pause is multiplied by the recovery multiplier, up to the maximum. A success ends the back-off. Evidence is still queued during a pause, and when a pause ends the queue drains without waiting for more requests. The pause and the resumption are logged.
6. Configuration options lists the five recovery options with .NET's defaults and the values they accept, in place of the rows that said they have no effect, and says an implementation MUST reject a value outside those.
7. Session tracking makes the repeat Evidence interval a sliding window that starts again each time Evidence is shared, so identical Evidence is shared at most once in each interval. The time MUST NOT be reset when matching Evidence is seen but not shared. The table row says the same.
8. Cleanup MUST NOT wait for a pause or send during one, and Error handling says nothing is logged for each entry dropped from a full queue.

The languages

Language	Back-off	Repeat interval
.NET	51degrees-dotnet#88 restores it	51degrees-dotnet#87 stores the time a repeat is shared
Java	51degrees-java#62 adds it	51degrees-java#61 stores the time a repeat is shared
Python	51degrees-python#53 adds it, with a maximum queue size	Already follows the window
Node	51degrees-node#36 adds it, with a maximum queue size and a request timeout	Already follows the window
Go	Not yet. usagesharing.go has a bounded queue and a sender that does not depend on processing, but drops a failed batch and has no back-off or recovery settings.	Already follows the window (lines 561 to 582)
PHP	51degrees-php has no usage sharing element.

For review

1. The session cookie name has a different default in each language. .NET uses asp.net_sessionid and Java uses JSESSIONID (Constants.java line 27). Python and Node have no default (51degrees-python#50, 51degrees-node#35), so turning session tracking on there also needs the cookie named. The table gives .NET's default.
2. Cleanup. The existing cleanup steps ask for a final message with whatever is left in the queue. Python closes without sending a package smaller than the requested package size, and Node elements have no cleanup step. Neither is changed by the pull requests above.

Found, not changed

• Two open pull requests into main, #65 and #56, also change this file.

Checks

Documentation only. The diff adds the back-off section and the passages above, and changes the table rows for the repeat interval and the five recovery options. The new rows keep the table's column widths.

Related

• Python and Node gain a separate session tracking option, off by default, in 51degrees-python#50 and 51degrees-node#35.
• Java already has both session settings, setTrackSession and setSessionCookieName (ShareUsageBuilderBase.java lines 374 to 421), wired as .NET's are (ShareUsageBase.java lines 428 to 445).