Welcome to Stackalytics!¶
Stackalytics is a service that collects and processes development activity data such as commits, lines of code changed, and code reviews, and makes it possible to visualize them in a convenient web dashboard. The Stackalytics dashboard makes it possible to view data by project, company, contributor, and other factors.
API¶
Stackalytics JSON API v1.0¶
Note
JSON API v1.0 corresponds to Stackalytics v0.X
1 General API information¶
This section contains base info about the Stackalytics JSON API design.
1.2 Request / Response Types¶
The Stackalytics API default response format is “application/json”. However if HTTP attribute ‘callback’ is specified then JSONP response is returned. That allows to use response in client-side code and avoid same-host requests limitations.
Example:
GET /api/1.0/stats/companies
or
GET /api/1.0/stats/companies?callback=myCallback
Accept: application/javascript
1.3 Faults¶
The Stackalytics API returns an error response if a failure occurs while processing a request. Stackalytics uses only standard HTTP error codes. 4xx errors indicate problems in the particular request being sent from the client and 5xx errors indicate server-side problems.
2 Methods¶
2.1 Common Parameters¶
All requests support common set of parameters that allow to filter resulting data.
| Parameter | Description |
|---|---|
| release | Name of OpenStack release or ‘all’, by default current release |
| project_type | Type of project, by default ‘openstack’ |
| module | Name of module (repository name) |
| company | Company name |
| user_id | Launchpad id of user or email if no Launchpad id is mapped. |
| metric | Metric: e.g. ‘commits’, ‘loc’, ‘marks’, ‘emails’ |
2.1.1 Other query parameters¶
Data can be queried by time period:
| Parameter | Description |
|---|---|
| start_date | When the period starts |
| end_date | When the period ends |
Both start_date and end_date take as their argument Unix time
For example to specify 'Thu Jan 1 00:00:00 UTC 2015' the value would be
1420070400
Note that if both release and time period are specified then the data is selected for the
intersection (thus the useful way is to specify release as all).
2.2 Contribution by Modules¶
Description
Stats on contribution per modules. The data contains list of modules with their metric. Modules which metric is 0 are omitted.
Request
| Verb | URI | Description |
|---|---|---|
| GET | /api/1.0/stats/modules | Contribution by Modules |
Example Request
GET /api/1.0/stats/modules?release=havana&metric=commits&project_type=openstack&user_id=zulcss
Example Response
{
"stats": [
{
"metric": 18,
"id": "oslo-incubator",
"name": "oslo-incubator"
},
{
"metric": 7,
"id": "keystone",
"name": "keystone"
},
{
"metric": 1,
"id": "python-neutronclient",
"name": "python-neutronclient"
}
]
}
2.3 Contribution by Companies¶
Description
Stats on contribution per companies. The data contains list of companies with their metric. Companies which metric is 0 are omitted.
Request
| Verb | URI | Description |
|---|---|---|
| GET | /api/1.0/stats/companies | Contribution by Companies |
Example Request
GET /api/1.0/stats/companies?release=havana&metric=commits&project_type=openstack&module=neutron
Example Response
{
"stats": [
{
"metric": 155,
"id": "VMware",
"name": "VMware"
},
{
"metric": 76,
"id": "Mirantis",
"name": "Mirantis"
},
{
"metric": 53,
"id": "Red Hat",
"name": "Red Hat"
},
{
"metric": 49,
"id": "Cisco Systems",
"name": "Cisco Systems"
},
{
"metric": 46,
"id": "*independent",
"name": "*independent"
}
]
}
2.4 Contribution by Engineers¶
Description
Stats on contribution per engineers. The data contains list of engineers with their metric. Engineers who has metric 0 are omitted. For reviews also added column with review distribution.
Request
| Verb | URI | Description |
|---|---|---|
| GET | /api/1.0/stats/engineers | Contribution by Engineers |
Example Request: Commits
GET /api/1.0/stats/engineers?release=havana&metric=commits&project_type=openstack&module=pbr
Example Response
{
"stats": [
{
"metric": 54,
"id": "mordred",
"name": "Monty Taylor"
},
{
"metric": 6,
"id": "jdanjou",
"name": "Julien Danjou"
},
{
"metric": 4,
"id": "doug-hellmann",
"name": "Doug Hellmann"
},
{
"metric": 3,
"id": "slukjanov",
"name": "Sergey Lukjanov"
}
]
}
Example Request: Reviews
GET /api/1.0/stats/engineers?release=havana&metric=marks&project_type=openstack&module=pbr
Example Response
{
"stats": [
{
"comment": "1|3|55|45 (96.2%)",
"metric": 104,
"id": "mordred",
"name": "Monty Taylor"
},
{
"comment": "0|13|18|51 (84.1%)",
"metric": 82,
"id": "cboylan",
"name": "Clark Boylan"
},
{
"comment": "0|13|11|36 (78.3%)",
"metric": 60,
"id": "doug-hellmann",
"name": "Doug Hellmann"
}
]
}
2.5 Activity log¶
Description
Depending on selected metric Activity log contains commits, reviews, emails or blueprints.
Request
| Verb | URI | Description |
|---|---|---|
| GET | /api/1.0/activity | Activity log |
When querying the activity log, the page_size and start_record parameters can be used to manage the paging of results (splitting results over multiple requests/responses). The default value of page_size is 10.
Example Response
{
"activity": [
{
"record_type": "commit",
"primary_key": "63580a7298887e6909602d8d96859b4e96b017e3",
"commit_id": "63580a7298887e6909602d8d96859b4e96b017e3",
"user_id": "zulcss",
"launchpad_id": "zulcss",
"author_name": "Chuck Short",
"author_email": "chuck.short@canonical.com",
"module": "ceilometer",
"release": "havana",
"blueprint_id": [],
"bug_id": [],
"date": 1370134263,
"branches": "master",
"message": "Introduce py33 to tox.ini to make testing with python3 easier.\n",
"subject": "python3: Introduce py33 to tox.ini",
"change_id": [
"I96d1ecd3f0069295e27127239c83afc32673ffec"
],
"company_name": "Canonical",
"loc": 2,
"files_changed": 1,
"lines_added": 1,
"lines_deleted": 1
}
]
}
2.6 Contribution summary¶
Description
Get contribution summary: number of commits, locs, emails, drafted and completed blueprints, review marks with distribution per mark (-2..+2).
Request
| Verb | URI | Description |
|---|---|---|
| GET | /api/1.0/contribution | Contribution summary |
Example Response
{
"contribution": {
"loc": 252,
"new_blueprint_count": 2,
"email_count": 7,
"commit_count": 5,
"competed_blueprint_count": 0,
"marks": {
"0": 0,
"1": 12,
"2": 2,
"-1": 5,
"-2": 0
}
}
}
CLI Tools¶
stackalytics-processor¶
Run Stackalytics processor
usage: stackalytics-processor [-h] [--config-dir DIR] [--config-file PATH]
[--corrections-uri CORRECTIONS_URI]
[--days_to_update_members DAYS_TO_UPDATE_MEMBERS]
[--debug] [--default-data-uri DEFAULT_DATA_URI]
[--fetching-user-source FETCHING_USER_SOURCE]
[--gerrit-retry GERRIT_RETRY]
[--git-base-uri GIT_BASE_URI]
[--log-config-append PATH]
[--log-date-format DATE_FORMAT]
[--log-dir LOG_DIR] [--log-file PATH]
[--members-look-ahead MEMBERS_LOOK_AHEAD]
[--nodebug] [--nouse-journal] [--nouse-syslog]
[--nowatch-log-file]
[--read-timeout READ_TIMEOUT]
[--review-uri REVIEW_URI]
[--runtime-storage-uri RUNTIME_STORAGE_URI]
[--sources-root SOURCES_ROOT]
[--ssh-key-filename SSH_KEY_FILENAME]
[--ssh-username SSH_USERNAME]
[--syslog-log-facility SYSLOG_LOG_FACILITY]
[--translation-team-uri TRANSLATION_TEAM_URI]
[--use-journal] [--use-syslog]
[--watch-log-file]
optional arguments:
-h, --help show this help message and exit
--config-dir DIR Path to a config directory to pull `*.conf` files
from. This file set is sorted, so as to provide a
predictable parse order if individual options are
over-ridden. The set is parsed after the file(s)
specified via previous --config-file, arguments hence
over-ridden options in the directory take precedence.
--config-file PATH Path to a config file to use. Multiple config files
can be specified, with values in later files taking
precedence. Defaults to None.
--corrections-uri CORRECTIONS_URI
The address of file with corrections data
--days_to_update_members DAYS_TO_UPDATE_MEMBERS
Number of days to update members
--debug, -d If set to true, the logging level will be set to DEBUG
instead of the default INFO level.
--default-data-uri DEFAULT_DATA_URI
URI for default data. A local file can be used with
the prefix "file://". For example, default_data_uri =
file:///path/to/default_data.json
--fetching-user-source FETCHING_USER_SOURCE
Source for fetching user profiles
--gerrit-retry GERRIT_RETRY
How many times to retry after Gerrit errors
--git-base-uri GIT_BASE_URI
git base location
--log-config-append PATH, --log-config PATH, --log_config PATH
The name of a logging configuration file. This file is
appended to any existing logging configuration files.
For details about logging configuration files, see the
Python logging module documentation. Note that when
logging configuration files are used then all logging
configuration is set in the configuration file and
other logging configuration options are ignored (for
example, logging_context_format_string).
--log-date-format DATE_FORMAT
Defines the format string for %(asctime)s in log
records. Default: None . This option is ignored if
log_config_append is set.
--log-dir LOG_DIR, --logdir LOG_DIR
(Optional) The base directory used for relative
log_file paths. This option is ignored if
log_config_append is set.
--log-file PATH, --logfile PATH
(Optional) Name of log file to send logging output to.
If no default is set, logging will go to stderr as
defined by use_stderr. This option is ignored if
log_config_append is set.
--members-look-ahead MEMBERS_LOOK_AHEAD
How many member profiles to look ahead after the last
--nodebug The inverse of --debug
--nouse-journal The inverse of --use-journal
--nouse-syslog The inverse of --use-syslog
--nowatch-log-file The inverse of --watch-log-file
--read-timeout READ_TIMEOUT
Number of seconds to wait for remote response
--review-uri REVIEW_URI
URI of review system
--runtime-storage-uri RUNTIME_STORAGE_URI
Storage URI
--sources-root SOURCES_ROOT
The folder that holds all project sources to analyze
--ssh-key-filename SSH_KEY_FILENAME
SSH key for gerrit review system access
--ssh-username SSH_USERNAME
SSH username for gerrit review system access
--syslog-log-facility SYSLOG_LOG_FACILITY
Syslog facility to receive log lines. This option is
ignored if log_config_append is set.
--translation-team-uri TRANSLATION_TEAM_URI
URI of translation team data
--use-journal Enable journald for logging. If running in a systemd
environment you may wish to enable journal support.
Doing so will use the journal native protocol which
includes structured metadata in addition to log
messages.This option is ignored if log_config_append
is set.
--use-syslog Use syslog for logging. Existing syslog format is
DEPRECATED and will be changed later to honor RFC5424.
This option is ignored if log_config_append is set.
--watch-log-file Uses logging handler designed to watch file system.
When log file is moved or removed this handler will
open a new log file with specified path
instantaneously. It makes sense only if log_file
option is specified and Linux platform is used. This
option is ignored if log_config_append is set.
Developer Guide¶
Other Resources
Project hosting with Launchpad¶
The Stackalytics project homepage on Launchpad is https://launchpad.net/stackalytics.
Bug tracking¶
Report Stackalytics bugs at https://bugs.launchpad.net/stackalytics
Feature requests (Blueprints)¶
Stackalytics uses Launchpad Blueprints to track feature requests. Blueprints are at https://blueprints.launchpad.net/stackalytics.
Code Reviews with Gerrit¶
Stackalytics uses the Gerrit tool to review proposed code changes. The review site is https://review.openstack.org.
Gerrit is a complete replacement for Github pull requests. All Github pull requests to the Stackalytics repository will be ignored.
See Gerrit Workflow Quick Reference for information about how to get started using Gerrit. See Development Workflow for more detailed documentation on how to work with Gerrit.
Continuous Integration with Jenkins¶
Each change made to Stackalytics core code is tested with unit and integration tests and style checks flake8.
Unit tests and style checks are performed on public OpenStack Jenkins managed by Zuul. Unit tests are checked using both python 2.6 and python 2.7.
The result of those checks and Unit tests are +1 or -1 to Verify column in a code review from Jenkins user.