KeyServer Usage Events
Overview
KeyServer records various client actions in the KSUsage table.
The event type is stored as an integer in the usageEvent field, and text representations of the event are in the KSTermEvent table.
This document will describe the events in a bit more detail and explain when they will be written.
Event types and meanings
| 1 | obtain | license obtained |
A Site or Floating license was obtained. This means it was issued by the server, and simultaneously used by the client. This single event for Site and Floating licenses
implies both allocation and usage, whereas Leased and Node Locked licenses have two separate events. |
| 2 | return | license returned |
A Site or Floating license was returned. This means that at the same time it stopped being used by the client, it was revoked by the server. |
| 3 | launch | program launched | A controlled program was launched in a situation where KeyServer was counting the necessary license allocation in real time. Either KeyAccess was online and in communication
with KeyServer, or the license type was Leased or Node Locked and the client had a license allocation. |
| 4 | quit | program quit | A controlled program was quit in a situation where KeyServer was counting the necessary license allocation in real time. Either KeyAccess was online and in communication
with KeyServer, or the license type was Leased or Node Locked and the client had a license allocation. |
| 5 | queue | user placed on waiting queue | The user asked for a license which had all copies in use. The KeyServer queued the user so that when a copy
becomes available, the user is notified. |
| 6 | dequeue | user remove from waiting queue | The user was on a waiting queue for a license, and a copy became available. They were removed from the queue
and subsequently will be given the license. |
| 7 | deny | program launch denied | The client tried to run a controlled program for which the server did not grant a license. |
| 8 | logged launch | logged program launched, no license control | A logged program was launched while the client was connected to the server. In this case there is no associated license. |
| 9 | logged quit | logged program quit, no license control | A logged program was quit while the client was connected to the server. |
| 10 | launch offline | offline program launch, license granted | A program controlled by a Site or Floating license was launched offline. A license associated with the program is recorded in the event
by the server in an attempt to "count" the usage against some license, but since the usage occured offline, there is no way to know whether if it had been online, this license (or any license associated
with the program) would have been granted. |
| 11 | quit offline | offline program quit, license returned | A controlled program which was launched offline was quit. |
| 12 | logged launch offline | offline logged program launched, no license control | A logged program was either launched offline, or it was launched online, but the corresponding quit ultimately happened offline. |
| 13 | logged quit offline | offline logged program quit, no license control | A logged program was either quit offline, or was quit online but the corresponding launch was offline. |
| 14 | deny unkeyed | unkeyed program launch denied |
unused |
| 15 | logon | session logon | A user logged on to KeyServer. In the simplest case this corresponds with a user logging in to the local computer. However, this event can also be written if the user goes offline,
their session with KeyServer times out, then they come back online and reach KeyServer again. It will also be recorded if KeyServer is restarted, when clients that were connected to the old process initiate communication
with the new process. |
| 16 | logoff | session logoff | A user logged out of KeyServer. The user logged out of the local computer, or KeyServer stopped running, or the client lost its connection to the KeyServer and the session
timed out. |
| 17 | block | session blocked | A client tried to log into KeyServer but could not. Either the computer record is set to excluded, the connection is being attempted from a location which is not allowed
to connect, or the user was unable to authenticate. |
| 18 | info | server information | Currently not used. |
| 19 | up | server started | The KeyServer process started up. |
| 20 | down | server stopped | The KeyServer process stopped. |
| 21 | shadow info | shadow information | Currently not used. |
| 22 | shadow up | shadow started serving | A KeyShadow started to communicate with clients because the KeyServer could not be reached. |
| 23 | shadow down | shadow stopped serving | A KeyShadow stopped communicating with clients because the KeyServer came back. |
| 24 | audited | audit completed | A client finished sending a software audit to the KeyServer. |
| 25 | issued | server lease issued | A KeyServer license was issued to the client, enabling it to connect to KeyServer. |
| 26 | revoked | server lease revoked | A KeyServer license was revoked from the client, either due to client inactivity, or because the computer record was deleted or set to "Excluded". |
| 27 | license issued | license lease issued |
A Leased, Node Locked, or portable license was issued to the client and will count against the license limit until it is revoked, regardless of whether
it is actively in use. |
| 28 | license revoked | license lease revoked | A Leased, Node Locked, or portable license was revoked, and the client will no longer be able to use the license unless it is issued to the client again. |
| 29 | license start | license usage start | A client started using a license in order to enable the use of a program. |
| 30 | license stop | license usage stop | A client stopped using a license that it no longer needs in order to use any program. |
Events 1-4 can have a reason indicating "shutdown", "lost", or "crashed". This means that the client became unable to talk to the KeyServer for some reason, and the session timed out.
When this occurs, both the client and the server (if it is still running) know that the server will no longer be counting the usage. If the license is set to detachable, or it is a license
type that remains allocated to the client, the client will continue to run the associated program and will report the remainder of the usage to the Server later. If on the other hand the
license is Site or Floating, and is not set to be detachable, the client will force the user to quit the program.
Differences between 6.1 and 6.2
The primary difference between KeyServer 6.1 and 6.2 is that KeyServer 6.1 did not distinguish between license allocation and license use. For the most part, the only recorded events corresponded to license use.
The one exception was for portable events, the same event codes were used but the dates were those of the license allocation, as opposed to license use. As a result, there was no way to report on allocation for a node-locked license.
In 6.2, with the addition of new event types, one can report either on license usage or on license allocation, for any license type. This is perhaps most interesting for a Leased License, where usage and allocation are quite different,
but unlike a node locked license, allocation does more than just grow over time.
Another difference is in the use of "offline" events. 6.1 used offline events any time that usage was reported after the fact to the KeyServer. When a 6.2 KeyAccess cannot contact the KeyServer, it knows in some cases that it has
a license - and in these cases, the eventual usage that is written will not be considered "offline" since the server has accounted for the license allocation. So now in 6.2 "offline" does not mean strictly that the client could not
reach the server, but moreover that the client did not have a license allocated. In this case, the client does not know whether it would have been able to get a license allocation if it were online.
Selecting events for reporting
Generally when writing reports, multiple event types need to be selected depending on what type of data you wish to report on. Here are some examples:
- License allocation - 1, 2, 27, 28
- License usage within allocation - 1, 2, 29, 30
- All license usage (may exceed allocation) - 1, 2, 29, 30, 10, 11
- Controlled program usage - 3, 4, 10, 11
- All program usage - 3, 4, 8, 9, 10, 11, 12, 13
Also, depending on what you need to report on, you may wish to select only "end" events - e.g. license return but no license obtain.
|