npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@neighbourhoodie/opservatory-agent

v2.39.3

Published

A stat collection tool for CouchDB.

Downloads

396

Readme

opservatory-agent

Build Status JS Standard Style Greenkeeper badge

A software agent for communicating information about a CouchDB installation to Opservatory.

Usage

You can get this tool via NPM:

$ npm i -g @neighbourhoodie/opservatory-agent

Alternatively, you can download binary releases for these environments:

Old versions are available at:

  • https://opservatory.fra1.digitaloceanspaces.com/archive/{version}/{file}

Once installed, you can try the tool like this:

$ opservatory-agent cron
    --couch-url http://admin:password@localhost:5984
    --node-name a.b.c.d
    --service-token ...

Or run it to only get the output as a zipped json file locally like this:

$ opservatory-agent once
    --couch-url http://admin:password@localhost:5984
    --node-name a.b.c.d

This will gather information and upload it to Opservatory.Once completed, it should give you a success message like this:

Investigation completed in ${seconds}s.
Investigation results posted to https://opservatory.app

Opservatory analyses the information reported by the agent and provides reports to users about the health and security of their CouchDB installations.

For more usage information, run opservatory-agent --help.

Task Files

The agent uses task files to conduct its investigation. By default, it uses the 'standard' task suite, contained in tasks/standard.json, a JSON file containing an array where each element is an object representing a task for the collector to execute.

Tasks have these recognizes properties:

  • access: an object containing keys with jsonpath expressions. Task results are passed through these expressions and the results are mapped to the associated keys. For example: given the results of querying /_all_dbs, the access object { db: '$.*'} will result in [{ db: '_replicator' }, ...]. This is used to template route and name in sub-tasks.
  • after: an array of other task objects to run after this one. Arguments parsed with access from the task's results are merged with the task's own arguments and passed to these sub-tasks.
  • name: a friendly identifier for the task. Defaults to the task's route, and so is useful when that information may not reliably indicate the task's nature or purpose. Like route, this property is templated using handlebars.
  • mode: an optional key that can be set to try in order to indicate that a task should be skipped if it fails. By default, a task that fails halts the investigation.
  • query: an object whose properties are converted into a querystring and used in the task's request.
  • route: a URL fragment indicating the path of the task's request. Like name, this property is templated using handlebars.
  • save: a boolean flag for whether or not the result of a task should be saved. Useful for running tasks solely to populate their sub-tasks.
  • version: a semver version identifier that is tested against a version argument (if it is present) which should be acquired by querying the cluster's root endpoint (/).

Name and Route Templating

The keys name and route are templated using handlebars and the variables gathered by running a task result through the access filter plus any variables from parent tasks. The e helper encodes the parameter using encodeURIComponent so that database and document names can be properly mapped to a URL. In the example, the task which gathers a database's design documents uses the name {{e db}}/_design_docs to indicate that its nature, whereas the route is {{e db}}/_all_docs.

For more task examples, check the collector's default task file.

The Output Object

A collector's investigation will produce a .json.gz archive containing an object with these keys:

  • date: A timestamp in milliseconds since the UNIX epoch for when the investigation occurred.
  • host: The host that was investigated. For example: localhost:5984
  • results: Object containing all the results of the investigation.
  • runTime: How long the collection process took, in milliseconds.
  • version: The version of the collector used in the investigation

The results key contains an object keyed with all the results of the investigation. Each key corresponds to the name of some task that was run, for example: _all_dbs will contain the results of querying /_all_dbs, and $DB_NAME/_design_docs will contain the results of the route named $DB_NAME/_design_docs.

The object behind each of these keys comes directly from the result of the task's HTTP query, so for example _all_dbs might look like this:

{
	"_all_dbs": ["_replicator", ... ],
	...
}

The special _os key contains information about the system where the investigation was performed and includes data about system CPU, RAM, network, and disk. Here is an example output:

{
  "cpus": [
    {
      "model": "Intel(R) Core(TM) i7-7500U CPU @ 2.70GHz",
      "speed": 3174,
      "times": {
        "user": 2265800,
        "nice": 10800,
        "sys": 703400,
        "idle": 12098800,
        "irq": 0
      }
    },
    ...
  ],
  "disk": {
    "diskPath": "/",
    "free": 10341093376,
    "size": 110863347712
  },
  "network": {
    "lo": [
      {
        "address": "127.0.0.1",
        "netmask": "255.0.0.0",
        "family": "IPv4",
        "mac": "NO AWOO $350 PENALTY",
        "internal": true,
        "cidr": "127.0.0.1/8"
      },
      ...
    ],
    ...
  },
  "platform": "linux",
  "ram": {
    "free": 11225653248,
    "total": 16538009600
  },
  "release": "4.15.0-36-generic"
}

The NodeJS built-in library os can be used, by passing the --os flag, to investigate the host system. Here are the methods used to populate the results object:

Development & Testing

Get and build the tool locally with Git:

$ git clone [email protected]:neighbourhoodie/opservatory-agent.git
$ cd opservatory-agent
$ npm install

Now you can run the test suite like this:

$ npm test

Creating the binary files

We are using pkg to generate the binaries for the platforms we are currently supporting.

$ npm run releases

Please note that to generate the macOS arm64 release you need a M1 mac, Xcode and Xcode command line tools installed.

Release

We are using semantic-release to create releases in git (tag), GitHub (release) and in npm (version). This will be triggered by a GitHub Actions workflow once a PR get's merged to the main branch. We are also uploading the binaries generated by the GitHub Actions workflow into our Digital Ocean opservatory space.

License

Proprietary. Use only with permission of Neighbourhoodie Software GmbH.