Binocular

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 24 Open GitHub ↗

Time-based visualizations of combined software engineering data

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Binocular](https://raw.githubusercontent.com/INSO-World/Binocular/main/docs/assets/Logo-Text.png)

[![Build Offline-Binocular](https://github.com/INSO-TUWien/Binocular/actions/workflows/build-offline.yml/badge.svg)](https://github.com/INSO-TUWien/Binocular/actions/workflows/build-offline.yml)
[![Test ESLint](https://github.com/INSO-TUWien/Binocular/actions/workflows/eslint.yml/badge.svg)](https://github.com/INSO-TUWien/Binocular/actions/workflows/eslint.yml)
[![Docker Image CI](https://github.com/INSO-TUWien/Binocular/actions/workflows/build-docker.yml/badge.svg)](https://github.com/INSO-TUWien/Binocular/actions/workflows/build-docker.yml)

![Default Dashboard](https://raw.githubusercontent.com/INSO-World/Binocular/main/docs/assets/screenshots/Dashboard_Parameters%20and%20Authors.png))

Binocular is a tool for visualizing data from various software-engineering
tools. It works as a command-line tool run from a git-repository. When
run, Binocular will gather data from the repository and the GitHub or GitLab API
and persist it to a configured ArangoDB instance.

Binocular then hosts interactive visualizations about the gathered data
via a web-interface.

## Features

Binocular provides visualizations across several categories:

- **Commit Analytics** - Track code changes, additions/deletions over time, and author contributions
- **Issue Tracking** - Visualize issue lifecycles, sprint progress, and burndown charts
- **Build Monitoring** - Monitor CI/CD pipeline status and build success rates
- **Code Ownership** - Analyze who owns which parts of the codebase over time
- **Developer Expertise** - Assess knowledge distribution and expertise areas across team members
- **Team Collaboration** - Discover collaboration patterns and team dynamics through network graphs
- **Repository Statistics** - Overview dashboards with key project metrics

## Preview
- [Demo Page](https://inso-world.github.io/Binocular/)
- [Screenshots](docs/PREVIEW.md)

## Dependencies

* node.js 20 LTS
* ArangoDB (tested with 3.12)

### Running ArangoDB with Docker

If you don't want to install ArangoDB locally, you can run it using Docker:

``` shell
docker run -d --name binocular_db -p 8529:8529 -e ARANGO_NO_AUTH=1 arangodb:3.12
```

Or use the provided docker-compose to start only the database:

``` shell
docker compose up db
```

This will start ArangoDB on port 8529 with no authentication. You can then run Binocular locally against this database.

## Installation

Binocular is not yet published on the npm registry. To install it, you
should clone this repository and then link it:

``` shell
$ git clone https://github.com/INSO-TUWien/Binocular.git
$ cd Binocular
/Binocular $ npm install # <- this will install the dependencies Binocular needs
/Binocular $ npm link # <- this will make the `Binocular` executable available in your $PATH
```

### Configuration

As Binocular needs to access an ArangoDB instance (run `binocular setup` to access the ArangoDB download page),
you have to configure the database connection before you can use Binocular. This can be done in
the global Binocular configuration file `~/.binocularrc`. Additionally, the
configuration file also stores authentication credentials for the used
APIs. The configuration file is read by the [rc
module](https://www.npmjs.com/package/rc). Check its documentation to
see the supported formats. For the purpose of this README, we'll use
json.

For simpler configuration there is also a configuration assistant avaliable
by executing `binocular setup`.
It will ask you some questions about the repository and generate the config file for you.

#### Configuration options

- `gitlab`: Object holding gitlab configuration options
  - `url`: The URL to the GitLab-Instance you want to connect to. Use the
         base-url, not the API-URL (see the example)!
  - `project`: 
  - `token`: The personal access token generated by your GitLab user to
            use for authentication (see
            https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
- `github`: Object holding GitHub configuration options
  - `auth`: Can hold any options that the [github npm-module] can take, check its documentation.
- `arango`: Object holding arangodb-configuration
  - `host`: Hostname
  - `port`: Port
  - `user`: username
  - `password`: password
- `travis`: Object holding travis-ci configuration options
  - `token`: (_**Optional for public repositories**_) holds the different access tokens for public and private repositories (https://blog.travis-ci.com/2013-01-28-token-token-token)
    - `access`: Access tokens are used to interact with the Travis API
    - `travis`:  If you want to display the status image for a private repository.
  - `timeout`: (_**Optional**_) set the timeout to cancel api request  
- `indexers`: (_**Optional**_) Object holding indexer configuration options.
              Should only be used if the repository could not detect the indexers automatically.
  - `its`: Holds the name of the issue tracking system indexer, for instance, GitLab or GitHub
  - `ci`: Since the CI indexer importer is searching for the corresponding file in the repository, it can be necessary to specify the
          correct indexer like, for example, GitLab or GitHub.
- `fileRenameBranches`: Array containing all branches for which file renames should be indexed. Additions to files that were later renamed are therefore shown in the visualizations. Without tracking renames, addition numbers for authors may be inaccurate. Comes with a performance penalty at index time.
- `ignoreFiles`: Array containing files/directories ignored by the indexer. Useful for large files (like `package-lock.json`) or irrelevant directories. Wildcards (*) are supported, see example below.
         
A sample configuration file looks like this:

```json
{
  "gitlab": {
    "url": "https://gitlab.com/",
    "token": "YOUR_GITLAB_API_TOKEN"
  },
  "github": {
    "auth": {
      "type": "basic",
      "username": "YOUR_GITHUB_USER",
      "token": "YOUR_GITHUB_OAUTH_TOKEN"
    }
  },
  "arango": {
    "host": "127.0.0.1",
    "port": 8529,
    "user": "YOUR_ARANGODB_USER",
    "password": "YOUR_ARANGODB_PASSWORD"
  },
  "indexers": {
    "its": "github",
    "ci": "github" 
  },
  "fileRenameBranches": [
        "main",
        "develop"
    ],
    "ignoreFiles": [
        "*package-lock.json",
        "*docs/*"
    ]
}
```

You may override configuration options for specific projects by
placing another `.binocularrc` file in the project's root directory.

You may also modify a config to the `gitlab.json` file in `./binocular-frontend/config`. This file sets
the GitLab API settings for the CodeHotspots-visualization for
offline execution. This is only necessary if you want to automatically
set those options within, for example, a GitLab pipeline.

#### Configuration options
- `server`: GitLab API server url
- `projectId`: GitLab project ID

A sample configuration file looks like this:
``` json
{
  "server":"GITLAB_API_URL",
  "projectId":"GITLAB_PROJECT_ID"
}
```

## Usage

Binocular uses a command-based CLI. The main commands are:

- `binocular run [targetPath]` - Execute the backend indexer
- `binocular build` - Build the frontend
- `binocular export` - Export the database
- `binocular setup` - Configure Binocular

### Running Binocular

To run Binocular, execute `binocular run` from the repository you want to
analyze (you can try it on the Binocular-repo itself!). Binocular will
try to guess reasonable defaults for configuration based on your
`.git/config`.

Common options for `binocular run`:
- `--no-vcs` - Disable Version Control System indexing
- `--no-its` - Disable Issue Tracking System indexing
- `--no-ci` - Disable Continuous Integration indexing
- `--export` - Export the database after indexing

### Development

For development, you can run the backend and frontend separately:
``` shell
npm run dev
```
Or on Windows (does not support chaining of commands):
``` shell
npm run dev:concurrently
```
This will start both the node backend and the frontend dev server.

If you run Binocular for the first time, it may show errors for missing JSON files.
This happens because to build the frontend it needs an export of the database.
When the indexers finish, it will create the database export automatically.

After the exported JSON files of the database are available, you can
build an offline executable version of Binocular:
``` shell
npm run build:offline
```
This will create an html and js file in the dist folder that can be
opened without the backend running. It is also possible
to place exported JSON files from a different mining job under `./binocular-frontend-new/db_export/` and build the frontend. (Not
all features will be available in the offline build.)

For more information check `binocular -h`

### Running Frontend Only

To install and run only the frontend:
``` shell
npm run install:frontend
npm run dev:frontend
```

## Contributors

<h3>Core Team</h3>
<table>
 <tr>
 <td>
 <a href="https://github.com/nuberion" title="Johann Grabner">
 <img src="https://github.com/nuberion.png?size=120" alt="Johann Grabner" width="96" height="96"> 
 Johann Grabner
 </a>
 </td>
 <td>
 <a href="https://github.com/MaximilianZenz" title="Maximilian Zenz">
 <img src="https://github.com/MaximilianZenz.png?size=120" alt="Maximilian Zenz" width="96" height="96"> 
 Maximilian Zenz
 </a>
 </td>
 <td>
 <a href="https://github.com/uberroot4" title="Manuel Stöger">
 <img src="https://github.com/uberroot4.png?size=120" alt="Manuel Stöger" width="96" height="96"> 
 Manuel Stöger
 </a>
 </td>
 <td>
 <a href="https://github.com/Megalokom" title="Michael Strasser">
 <img src="https://github.com/Megalokom.png?size=120" alt="Michael Strasser" width="96" height="96"> 
 Michael Strasser
 </a>
 </td>
 </tr>
 <tr>
 <td>
 <a href="https://github.com/bastianferch" title="Bastian Ferch">
 <img src="https://github.com/bastianferch.png?size=120" alt="Bastian Ferch" width="96" height="96"> 
 Bastian Ferch
 </a>
 </td>
 <td>
 <a href="https://github.com/Markus99at" title="Markus Gumpoltsberger">
 <img src="https://github.com/Markus99at.png?size=120" alt="Markus Gumpoltsberger" width="96" height="96"> 
 Markus Gumpoltsberger
 </a>
 </td>
 <td>
 <a href="https://github.com/kkastenmeier" title="Kai Kastenmeier">
 <img src="https://github.com/kkastenmeier.png?size=120" alt="Kai Kastenmeier" width="96" height="96"> 
 Kai Kastenmeier
 </a>
 </td>
 <td>
 <a href="https://github.com/Nyzabes" title="Sebastian Watzinger">
 <img src="https://github.com/Nyzabes.png?size=120" alt="Sebastian Watzinger" width="96" height="96"> 
 Sebastian Watzinger
 </a>
 </td>
 </tr>
</table>

<h3>Bachelor/Master-Theses</h3>
<table>
 <tr>
 <td>
 <a href="https://github.com/romandecker" title="Roman Decker">
 <img src="https://github.com/romandecker.png?size=120" alt="Roman Decker" width="96" height="96"> 
 Roman Decker
 </a>
 </td>
 <td>
 <a href="https://github.com/alexnefi" title="Alexander Nemetz-Fiedler">
 <img src="https://github.com/alexnefi.png?size=120" alt="Alexander Nemetz-Fiedler" width="96" height="96"> 
 Alexander Nemetz-Fiedler
 </a>
 </td>
 <td>
 <a href="https://github.com/THMv1TU" title="Michael Thurner">
 <img src="https://github.com/THMv1TU.png?size=120" alt="Michael Thurner" width="96" height="96"> 
 Michael Thurner
 </a>
 </td>
 <td>
 <a href="https://github.com/schoeberlt" title="Tamas Schöberl">
 <img src="https://github.com/schoeberlt.png?size=120" alt="Tamas Schöberl" width="96" height="96"> 
 Tamas Schöberl
 </a>
 </td>
 </tr>
 <tr>
 <td>
 <a href="https://github.com/belthazors" title="Amar Kasic">
 <img src="https://github.com/belthazors.png?size=120" alt="Amar Kasic" width="96" height="96"> 
 Amar Kasic
 </a>
 </td>
 <td>
 <a href="https://github.com/juliankotrba" title="Julian Kotrba">
 <img src="https://github.com/juliankotrba.png?size=120" alt="Julian Kotrba" width="96" height="96"> 
 Julian Kotrba
 </a>
 </td>
 <td>
 <a href="https://github.com/matthiasweiss" title="Matthias Weiß">
 <img src="https://github.com/matthiasweiss.png?size=120" alt="Matthias Weiß" width="96" height="96"> 
 Matthias Weiß
 </a>
 </td>
 <td>
 <a href="https://github.com/Thoma5" title="Thomas Mörbauer">
 <img src="https://github.com/Thoma5.png?size=120" alt="Thomas Mörbauer" width="96" height="96"> 
 Thomas Mörbauer
 </a>
 </td>
 </tr>
 <tr>
 <td>
 <a href="https://github.com/m4nv3ru" title="Michael Kurz">
 <img src="https://github.com/m4nv3ru.png?size=120" alt="Michael Kurz" width="96" height="96"> 
 Michael Kurz
 </a>
 </td>
 <td>
 <a href="https://github.com/profjellybean" title="Valentin Schnabl">
 <img src="https://github.com/profjellybean.png?size=120" alt="Valentin Schnabl" width="96" height="96"> 
 Valentin Schnabl
 </a>
 </td>
 <td>
 <a href="https://github.com/Soleymantic" title="Solaiman Nejat">
 <img src="https://github.com/Soleymantic.png?size=120" alt="Solaiman Nejat" width="96" height="96"> 
 Solaiman Nejat
 </a>
 </td>
 <td>
 <a href="https://github.com/Grochni" title="Christian Gröchenig">
 <img src="https://github.com/Grochni.png?size=120" alt="Christian Gröchenig" width="96" height="96"> 
 Christian Gröchenig
 </a>
 </td>
 </tr>
 <tr>
 <td>
 <a href="https://github.com/raini90" title="Rainhard Pfneiszl">
 <img src="https://github.com/raini90.png?size=120" alt="Rainhard Pfneiszl" width="96" height="96"> 
 Rainhard Pfneiszl
 </a>
 </td>
 <td>
 <a href="https://github.com/codester007" title="Valentin Kastberger">
 <img src="https://github.com/codester007.png?size=120" alt="Valentin Kastberger" width="96" height="96"> 
 Valentin Kastberger
 </a>
 </td>
 <td>
 <a href="https://github.com/AM307" title="André Mategka">
 <img src="https://github.com/AM307.png?size=120" alt="André Mategka" width="96" height="96"> 
 André Mategka
 </a>
 </td>
 <td>
 <a href="https://github.com/Bene-dykt" title="Benedikt Eckerstorfer">
 <img src="https://github.com/Bene-dykt.png?size=120" alt="Benedikt Eckerstorfer" width="96" height="96"> 
 Benedikt Eckerstorfer
 </a>
 </td>
 </tr>
 <tr>
 <td>
 <a href="https://github.com/DominikKidery" title="Dominik Kidery">
 <img src="https://github.com/DominikKidery.png?size=120" alt="Dominik Kidery" width="96" height="96"> 
 Dominik Kidery
 </a>
 </td>
 <td>
 <a href="https://github.com/peter-kotouc" title="Peter Kotouč">
 <img src="https://github.com/peter-kotouc.png?size=120" alt="Peter Kotouč" width="96" height="96"> 
 Peter Kotouč
 </a>
 </td>
 <td>
 <a href="https://github.com/TBalint2000" title="Bálint Timár">
 <img src="https://github.com/TBalint2000.png?size=120" alt="Bálint Timár" width="96" height="96"> 
 Bálint Timár
 </a>
 </td>
 <td>
 <a href="https://github.com/maerzman" title="Manuel Märzinger">
 <img src="https://github.com/maerzman.png?size=120" alt="Manuel Märzinger" width="96" height="96"> 
 Manuel Märzinger
 </a>
 </td>
 </tr>
 <tr>
 <td>
 <a href="https://github.com/martan001" title="Anton Martinovic">
 <img src="https://github.com/martan001.png?size=120" alt="Anton Martinovic" width="96" height="96"> 
 Anton Martinovic
 </a>
 </td>
 <td>
 <a href="https://github.com/ValentinFutterer" title="Valentin Futterer">
 <img src="https://github.com/ValentinFutterer.png?size=120" alt="Valentin Futterer" width="96" height="96"> 
 Valentin Futterer
 </a>
 </td>
 <td>
 <a href="https://github.com/MoravekJakub" title="Jakub Morávek">
 <img src="https://github.com/MoravekJakub.png?size=120" alt="Jakub Morávek" width="96" height="96"> 
 Jakub Morávek
 </a>
 </td>
 <td>
 <a href="https://github.com/R0555" title="Ross Boulton">
 <img src="https://github.com/R0555.png?size=120" alt="Ross Boulton" width="96" height="96"> 
 Ross Boulton
 </a>
 </td>
 </tr>
 <tr>
 <td>
 <a href="https://github.com/DangeeundDu" title="Martin Weber">
 <img src="https://github.com/DangeeundDu.png?size=120" alt="Martin Weber" width="96" height="96"> 
 Martin Weber
 </a>
 </td>
 <td>
 <a href="https://github.com/thimonpelka" title="Thimon Pelka">
 <img src="https://github.com/thimonpelka.png?size=120" alt="Thimon Pelka" width="96" height="96"> 
 Thimon Pelka
 </a>
 </td>
 <td>
 <a href="https://github.com/Sebastian-Schuch" title="Sebastian Schuch">
 <img src="https://github.com/Sebastian-Schuch.png?size=120" alt="Sebastian Schuch" width="96" height="96"> 
 Sebastian Schuch
 </a>
 </td>
 <td>
 <a href="https://github.com/SurfingCaterpillar" title="Sarah Biedermann">
 <img src="https://github.com/SurfingCaterpillar.png?size=120" alt="Sarah Biedermann" width="96" height="96"> 
 Sarah Biedermann
 </a>
 </td>
 </tr>
 <tr>
 <td>
 <a href="https://github.com/FreshGuy32" title="Mathias Trapl">
 <img src="https://github.com/FreshGuy32.png?size=120" alt="Mathias Trapl" width="96" height="96"> 
 Mathias Trapl
 </a>
 </td>
 <td></td>
 <td></td>
 <td></td>
 </tr>
</table>

## Contributing

**:warning: Binocular is currently in a transition state from javascript to typescript.
Although it is compatible with both javascript and typescript components, new visualizations
should be implemented in typescript.
Please refer to the change visualization/visualization Component
if you are unsure how to implement a visualization in typescript.**

For an explanation of Binocular's architecture, please see the [Contribution
guidelines for this project](docs/CONTRIBUTING.md)

For an overview of the database collections and connections Binocular creates,
please see the [database documentation](docs/DATABASE.md)

Binocular

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README