mongoscope-client/README.md

shush

# mongoscope-client

[![build status](https://secure.travis-ci.org/imlucas/mongoscope-client.png)](http://travis-ci.org/imlucas/mongoscope-client)

A client for wielding [mongoscope](http://github.com/10gen/mongoscope) like the hammer of thor.

Examples are available in `./examples` and as a [Codepen Collection](http://codepen.io/collection/Gdeok/).

```
npm install --save mongoscope-client
```

## API

```javascript
var mongoscope = require('mongoscope-client')([opts]);
```

#### Parameters

- `opts` (optional, Object) ...
    - `scope` (String) ... Where mongoscope-server is running default `http://localhost:29017`
    - `seed` (String) ... Hostport of mongodb instance default `localhost:27017`
    - `auth` (Object) ... Auth spec default `{}`

### resource

Create, read, update and destroy databases, collections, documents and indices.

#### mongoscope.instance(opts, fn)

![production](http://b.repl.ca/v1/stability-production-green.png)

Get details of the instance you're currently connected to
like database_names, results of the hostInfo and buildInfo mongo commands.
##### Parameters

- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.deployments(opts, fn)

![production](http://b.repl.ca/v1/stability-production-green.png)

List all deployments this mongoscope instance has connected to.

##### Parameters

- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.database(name, opts, fn)

![production](http://b.repl.ca/v1/stability-production-green.png)

List collection names and stats.

##### Parameters

- `name` (required, String)
- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.collection(ns, opts, fn)

![production](http://b.repl.ca/v1/stability-production-green.png)

Collection stats

##### Parameters

- `ns` (required, String) ... A namespace string, eg `#{database_name}.#{collection_name}`
- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.operation(_id, opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

A currently running operation.

##### Parameters

- `_id` (required, Number)
- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.index(ns, name, opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Index details

##### Parameters

- `ns` (required, String) ... A namespace string, eg `#{database_name}.#{collection_name}`
- `name` (required, String) ... The index name
- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.document(ns, _id, opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Work with a single document.

##### Parameters

- `ns` (required, String) ... A namespace string, eg `#{database_name}.#{collection_name}`
- `_id` (required, String) ... The document's `_id` value
- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.tunnel()

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Open an ssh tunnel to securely connect to a remote host.

### rt

Run MongoDB query operations, including virtual operations such as collection sampling.

#### mongoscope.top(opts, fn)

![production](http://b.repl.ca/v1/stability-production-green.png)

Capture the deltas of top over `opts.interval` ms.

##### Parameters

- `opts` (optional, Object) ... Placeholder for future options
    - `interval` (Number) ... Duration of sample in ms default `1000`

- `fn` (required, Function) ... A response callback `(err, data)`

#### mongoscope.log(opts, fn)

![production](http://b.repl.ca/v1/stability-production-green.png)

A structured view of the ramlog.

##### Parameters

- `opts` (optional, Object) ... Placeholder for future options
- `fn` (required, Function) ... A response callback `(err, data)`

#### mongoscope.ops(opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

List currently running operations.

##### Parameters

- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.sharding(opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Get the sharding info for the cluster the instance you're connected
to is a member of, similar to the `printShardingStatus()` helper function
in the mongo shell.

##### Examples

- [Sharding Report](http://codepen.io/imlucas/pen/JgzAh)

##### Parameters

- `opts` (optional, Object) ... Placeholder for future options
- `fn` (required, Function) ... A response callback `(err, data)`

#### mongoscope.replication(opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

View current state of all members and oplog details.
##### Parameters

- `opts` (optional, Object) ... Placeholder for future options
- `fn` (required, Function) ... A response callback `(err, data)`

#### mongoscope.oplog(opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Get oplog entries.

##### Parameters

- `opts` (optional, Object) ...
    - `since` (Number) ... Epoch time lower bounds default `Date.now() - 1000 * 60`
    - `filters` (Array) ... List of tuples `({key}, {regex})` default `[]`

- `fn` (required, Function) ... A response callback `(err, data)`

#### mongoscope.analytics(group, opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Get or stream a group of analytics, which can be any of one
durability, operations, memory, replication, network or indexes.

##### Parameters

- `group` (required, String)
- `opts` (optional, Object) ... Placeholder for future options
- `fn` (optional, Function) ... A response callback `(err, data)`

### query

Run MongoDB query operations, including virtual operations such as collection sampling.

#### mongoscope.find(ns, opts, fn)

![production](http://b.repl.ca/v1/stability-production-green.png)

Run a query on `db.collection`.

##### Parameters

- `ns` (required, String) ... A namespace string, eg `#{database_name}.#{collection_name}`
- `opts` (optional, Object) ... Placeholder for future options
    - `query` (Object) ... default `{}`
    - `limit` (Number) ... default `10`, max 200
    - `skip` (Number) ... default 0
    - `explain` (Boolean) ... Return explain instead of documents default `false`
    - `sort` (Object) ... `{key: (1|-1)}` spec default `null`
    - `fields` (Object) ... @todo
    - `options` (Object) ... @todo
    - `batchSize` (Number) ... @todo

- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.count(ns, opts, fn)

![production](http://b.repl.ca/v1/stability-production-green.png)

Run a count on `db.collection`.

##### Parameters

- `ns` (required, String) ... A namespace string, eg `#{database_name}.#{collection_name}`
- `opts` (optional, Object) ...
    - `query` (Object) ... default `{}`
    - `limit` (Number) ... default `10`, max 200
    - `skip` (Number) ... default 0
    - `explain` (Boolean) ... Return explain instead of documents default `false`
    - `sort` (Object) ... `{key: (1|-1)}` spec default `null`
    - `fields` (Object) ... @todo
    - `options` (Object) ... @todo
    - `batchSize` (Number) ... @todo

- `fn` (optional, Function) ... A response callback `(err, data)`

#### mongoscope.aggregate(ns, pipeline, opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Run an aggregation pipeline on `db.collection`.

##### Examples

- [Run an aggregation and chart it](http://codepen.io/imlucas/pen/BHvLE)

##### Parameters

- `ns` (required, String) ... A namespace string, eg `#{database_name}.#{collection_name}`
- `pipeline` (required, Array)
- `opts` (optional, Object) ...
    - `explain` (Boolean) ... @todo
    - `allowDiskUse` (Boolean) ... @todo
    - `cursor` (Object) ... @todo

- `fn` (required, Function) ... A response callback `(err, data)`

#### mongoscope.sample(ns, opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Use [resevoir sampling](http://en.wikipedia.org/wiki/Reservoir_sampling) to
get a slice of documents from a collection efficiently.

##### Parameters

- `ns` (required, String) ... A namespace string, eg `#{database_name}.#{collection_name}`
- `opts` (optional, Object) ...
    - `size` (Number) ... The number of samples to obtain default `5`
    - `query` (Object) ... Restrict the sample to a subset default `{}`

- `fn` (required, Function) ... A response callback `(err, data)`

#### mongoscope.random(ns, opts, fn)

![development](http://b.repl.ca/v1/stability-development-yellow.png)

Convenience to get 1 document via `Client.prototype.sample`.

##### Parameters

- `ns` (required, String) ... A namespace string, eg `#{database_name}.#{collection_name}`
- `opts` (optional, Object) ...
    - `query` (Object) ... Restrict the sample to a subset default `{}`

- `fn` (required, Function) ... A response callback `(err, data)`

#### mongoscope.workingSet(opts, fn)

![prototype](http://b.repl.ca/v1/stability-prototype-orange.png)

Working set size estimator.
##### Parameters

- `opts` (optional, Object)
- `fn` (required, Function) ... A response callback `(err, data)`