title: analytics/session_tick
description: >
  Each active user session sends its current length at a pre-determined time
  interval called a 'tick'. When a user session becomes inactive, it stops
  sending length updates. If it remains inactive long enough, it will be reset.
  If it re-activates before being reset, the backlog of length updates will be
  sent, and it will resume sending length updates as before.

  Used to compute a privacy-conscious session length metric, see
  https://wikitech.wikimedia.org/wiki/Analytics/Data_Lake/Traffic/SessionLength
$id: /analytics/session_tick/1.0.0
$schema: 'https://json-schema.org/draft-07/schema#'
type: object
additionalProperties: false
required:
  - $schema
  - meta
  - tick
properties:
  $schema:
    description: >
      A URI identifying the JSONSchema for this event. This should match an
      schema's $id in a schema repository. E.g. /schema/title/1.0.0
    type: string
  meta:
    type: object
    required:
      - dt
      - stream
    properties:
      uri:
        type: string
        format: uri-reference
        maxLength: 8192
        description: Unique URI identifying the event or entity
      request_id:
        description: Unique ID of the request that caused the event
        type: string
      id:
        description: Unique ID of this event
        type: string
      dt:
        type: string
        format: date-time
        maxLength: 128
        description: 'UTC event datetime, in ISO-8601 format'
      domain:
        description: Domain the event or entity pertains to
        type: string
        minLength: 1
      stream:
        description: Name of the stream/queue/dataset that this event belongs in
        type: string
        minLength: 1
  http:
    type: object
    properties:
      protocol:
        description: The protocol used for the request (HTTP or HTTPS)
        type: string
      method:
        description: 'The HTTP request method (GET, POST, etc.)'
        type: string
      status_code:
        description: The HTTP status code returned for this request (when known)
        type: integer
        minimum: -9007199254740991
        maximum: 9007199254740991
      has_cookies:
        description: True if the http request has any cookies set
        type: boolean
      request_headers:
        description: 'Request headers sent by the client.  E.g. user-agent, etc.'
        type: object
        additionalProperties:
          type: string
      response_headers:
        description: Response headers sent back to the client (when known).
        type: object
        additionalProperties:
          type: string
  client_dt:
    type: string
    format: date-time
    maxLength: 128
    description: >
      ISO-8601 formatted timestamp of when the event occurred/was generated in
      UTC). This exists separately from meta.dt in the main common schema. For
      external client-sent instrumentation events, we want to allow meta.dt to
      be the received time (filled in by EventGate at ingest time), as we don't
      trust client-sent events to always set the proper date and time.
      Client-set event generation time should be set here instead. See:
      https://phabricator.wikimedia.org/T240460
  tick:
    description: >
      Current length of the client session, expressed as number of ticks. Loss
      of precision from denominating length in tick units (vs. ms) simplifies
      aggregation and enhances privacy.
    type: integer
    minimum: 0
    maximum: 9007199254740991
  config_tick_ms:
    description: >
      Unit of time, in milliseconds, each tick represents. Gets value from
      MediaWiki config variable; included for data lineage.
    type: integer
    minimum: -9007199254740991
    maximum: 9007199254740991
  config_idle_ms:
    description: >
      Milliseconds of inactivity until a page is marked idle. Gets value from
      MediaWiki config variable; included for data lineage.
    type: integer
    minimum: -9007199254740991
    maximum: 9007199254740991
  config_reset_ms:
    description: >
      Milliseconds until session is reset if all pages are idle. Gets value from
      MediaWiki config variable; included for data lineage.
    type: integer
    minimum: -9007199254740991
    maximum: 9007199254740991
  test:
    description: >
      A string:integer 'map' type for carrying temporary test values e.g. for
      validation, compatibility, etc. This field should be treated as volatile
      and its data should not be retained.
    type: object
    additionalProperties:
      type: integer
      minimum: -9007199254740991
      maximum: 9007199254740991
examples:
  - $schema: /analytics/session_tick/1.0.0
    meta:
      stream: session_tick_example
      domain: es.m.wikipedia.org
      dt: '2020-06-11T19:20:00.649Z'
    tick: 2
    config_tick_ms: 10000
    config_idle_ms: 30000
    config_reset_ms: 60000
    test:
      supports_passive: 1
    client_dt: '2020-06-11T19:20:00.649Z'