job-pulse.yml

$schema: "http://json-schema.org/draft-04/schema#"
title: "Job Definition"
description: |
  Definition of a single job that can be added to Treeherder
  Project is determined by the routing key, so we don't need to specify it here.
id: "jobDefinition"
type: "object"
properties:
  taskId:
    title: "taskId"
    descriptio: |
      This could just be what was formerly submitted as a job_guid in the
      REST API.
    type: "string"
    pattern: "^[A-Za-z0-9_/+-]+$"
    minLength: 1
    maxLength: 50
  retryId:
    title: "retryId"
    description: |
      The infrastructure retry iteration on this job.  The number of times this
      job has been retried by the infrastructure.
      If it's the 1st time running, then it should be 0. If this is the first
      retry, it will be 1, etc.
    type: "integer"
    default: 0
    minimum: 0

  isRetried:
    description: True indicates this job has been retried.
    type: "boolean"

  origin:
    oneOf:
      - type: "object"
        properties:
          kind:
            type: "string"
            enum: ['hg.mozilla.org']
          project:
            type: "string"
            pattern: "^[A-Za-z0-9_-]+$"
            minLength: 1
            maxLength: 50
          revision:
            type: "string"
            pattern: "^[0-9a-f]+$"
            minLength: 40
            maxLength: 40
          pushLogID:
            type: "integer"
        required: [kind, project, revision]

      - type: "object"
        properties:
          kind:
            type: "string"
            enum: ['github.com']
          owner:
            description: |
              This could be the organization or the individual git username
              depending on who owns the repo.
            type: "string"
            pattern: "^[0-9a-f]+$"
            minLength: 1
            maxLength: 50
          projectName:
            type: "string"
            pattern: "^[0-9a-f]+$"
            minLength: 1
            maxLength: 50
          revision:
            type: "string"
            minLength: 40
            maxLength: 40
          pullRequestID:
            type: "integer"
        required: [kind, project, revision]

  display:
    type: "object"
    properties:
      anyOf:
        jobSymbol:
          title: "jobSymbol"
          type: "string"
          # spaces and "?" are not valid for job symbols
          pattern: "^[A-Za-z0-9._-]+$"
          minLength: 1
          maxLength: 25
        chunkId:
          title: "chunkId"
          type: "integer"
          minimum: 1
      chunkCount:
        title: "chunkCount"
        type: "integer"
        minimum: 1
      groupSymbol:
        title: "group symbol"
        type: "string"
        # spaces not valid for group symbols
        pattern: "^[A-Za-z0-9/?_-]+$"
        minLength: 1
        maxLength: 25
      # could do without these if we require job type and group to exist prior
      jobName:
        title: "job name"
        type: "string"
        minLength: 1
        maxLength: 100
      groupName:
        title: "group name"
        type: "string"
        pattern: "^[A-Za-z0-9_-]+$"
        minLength: 1
        maxLength: 100
    required:
      - groupSymbol


  state:
    title: "state"
    description: |
      unscheduled: not yet scheduled
      pending: not yet started
      running: currently in progress
      completed: Job ran through to completion
    type: "string"
    enum:
      - unscheduled
      - pending
      - running
      - completed
  result:
    title: "result"
    description: |
      fail: A failure
      exception: An infrastructure error/exception
      success: Build/Test executed without error or failure
      canceled: The job was cancelled by a user
      unknown: When the job is not yet completed
    type: "string"
    enum:
      - success
      - fail
      - exception
      - canceled
      - unknown
  jobKind:
    type: "string"
    default: "other"
    enum:
      - build
      - test
      - other
  tier:
    type: "integer"
    minimum: 1
    maximum: 3

  coalesced:
    description: The job guids that were coalesced to this job.
    title: "coalesced"
    type: "array"
    items:
      title: "job guid"
      type: "string"
      pattern: "^[A-Za-z0-9_/+-]+$"
      minLength: 1
      maxLength: 50


  # time data
  timeScheduled:
    type: "string"
    format: "date-time"
  timeStarted:
    type: "string"
    format: "date-time"
  timeCompleted:
    type: "string"
    format: "date-time"

  labels:
    title: "labels"
    description: |
      Labels are a dimension of a platform.  The values here can vary wildly,
      so most strings are valid for this.  The list of labels that are used
      is maleable going forward.

      These were formerly known as "Options" within "Option Collections" but
      calling labels now so they can be understood to be just strings that
      denotes a characteristic of the job.

      Some examples of labels that have been used:
        opt    Optimize Compiler GCC optimize flags
        debug  Debug flags passed in
        pgo    Profile Guided Optimization - Like opt, but runs with profiling, then builds again using that profiling
        asan   Address Sanitizer
        tsan   Thread Sanitizer Build
    type: "array"
    items:
      type: "string"
      minLength: 1
      maxLength: 50
      pattern: "^[A-Za-z0-9_-]+$"

  owner:
    description: |
      Description of who submitted the job: gaia | scheduler name | username | email
    title: "owner"
    type: "string"
    minLength: 1
    maxLength: 50
  reason:
    description: |
      Examples include:
      - scheduled
      - scheduler
      - Self-serve: Rebuilt by foo@example.com
      - Self-serve: Requested by foo@example.com
      - The Nightly scheduler named 'b2g_mozilla-inbound periodic' triggered this build
      - unknown
    type: "string"
    minLength: 1
    maxLength: 125
  productName:
    description: |
      Examples include:
      -  'b2g'
      -  'firefox'
      -  'taskcluster'
      -  'xulrunner'
    type: "string"
    minLength: 1
    maxLength: 125

  buildMachine:
    $ref: "#/definitions/machine"
  runMachine:
    $ref: "#/definitions/machine"

  summary:
    type: string
    description: |
      Markdown description of the job and it's state. New messages about a task
      should not contain the same `summary` as previous message. Treeherder will
      combine the `summary` from all messages in order the messages arrive.
      This will be rendered to HTML and displayed in treeherder, you may include
      links, but raw HTML is forbidding.
    maxLength: 4096

  talosResults:
    type: array
    description: List of talos results.
    items:
      type: object
      description: Result from a talos suite.
      properties:
        suite:
          type: string
          description: Name of the talos suite
        url:
          type: string
          format: uri
          description: URL to the talos results
        result:
          type: number
          description: Talos score for the suite

  logs:
    type: "array"
    description: |
      List of logs attached to the task.
      When a log have been reported in a messsage subsequent messages need not
      contain log. But if a log with the same `name` is reported, it will
      overwrite the previous entry.
    items:
      type: "object"
      properties:
        url:
          type: "string"
          format: "uri"
          minLength: 1
          maxLength: 255
        name:
          type: "string"
          minLength: 1
          maxLength: 50
        stepsUrl:
          type: string
          format: uri
          description: |
            Optional URL to the parsed meta-data.
      required: [url, name]

  extra:
    type: "object"
    description: Extra information that Treeherder reads on a best-effort basis

additionalProperties: false
required:
  - taskId
  - origin
  - display
  - state
  - jobKind

definitions:
  machine:
    type: "object"
    properties:
      name:
        type: "string"
        pattern: "^[A-Za-z0-9_-]+$"
        minLength: 1
        maxLength: 50
      platform:
        type: "string"
        pattern: "^[A-Za-z0-9_-]+$"
        minLength: 1
        maxLength: 25
      os:
        type: "string"
        pattern: "^[A-Za-z0-9_-]+$"
        minLength: 1
        maxLength: 25
      architecture:
        type: "string"
        pattern: "^[A-Za-z0-9_-]+$"
        minLength: 1
        maxLength: 25
    required:
      - name
      - platform
      - os
      - architecture