Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tlux/vnstat-ruby
A Ruby solution to retrieve network traffic information using the vnstat command line utility.
https://github.com/tlux/vnstat-ruby
gem network-monitoring networking ruby ruby-gem traffic-information vnstat
Last synced: 5 days ago
JSON representation
A Ruby solution to retrieve network traffic information using the vnstat command line utility.
- Host: GitHub
- URL: https://github.com/tlux/vnstat-ruby
- Owner: tlux
- License: mit
- Created: 2015-11-17T21:08:13.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-03-01T16:51:17.000Z (9 months ago)
- Last Synced: 2024-03-15T14:11:20.537Z (8 months ago)
- Topics: gem, network-monitoring, networking, ruby, ruby-gem, traffic-information, vnstat
- Language: Ruby
- Homepage:
- Size: 147 KB
- Stars: 6
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# vnstat-ruby
[](https://travis-ci.org/tlux/vnstat-ruby)
[](https://coveralls.io/github/tlux/vnstat-ruby?branch=master)
[](https://badge.fury.io/rb/vnstat-ruby)
Vnstat is a tool that tracks the traffic on your network interfaces.
This tiny library is intended to provide network traffic information
through an easy-to-use API.
It depends on the
[vnstat command line utility](http://humdi.net/vnstat/) which is
maintained by Teemu Toivola.
### Prerequisites
* Ruby 2.3.0 or greater
* Make sure you have `vnstat` CLI installed by running `which vnstat`.
On Ubuntu you can get the vnstat package via `apt-get install vnstat`.
### Getting Started
#### Setup
Once the dependent package is installed, you are ready to install the
vnstat-ruby gem.
```bash
gem install vnstat-ruby
```
Or, add the following line to the Gemfile of your project and run the
`bundle install` command:
```ruby
gem 'vnstat-ruby'
```
#### Configuration
By default, vnstat-ruby tries to automatically determine the location of your
vnstat executable. If you need to change this path for some reason, you can
override the default:
```ruby
Vnstat.config.executable_path = '/usr/bin/vnstat'
```
### Usage
#### Network Interfaces
To retrieve a list of all known network interfaces:
```ruby
Vnstat.interfaces # => #
Vnstat.interfaces.ids # => ['eth01', 'eth02']
```
To only retrieve traffic stats for a single interface:
```ruby
Vnstat.interfaces.first # => #
```
If you know the name of a network interface, you can also retrieve the
stats of that particular one:
```ruby
Vnstat['eth01'] # => #
```
#### Traffic Information
##### Total
```ruby
interface = Vnstat['eth01']
```
```ruby
interface.total # => #
interface.total.bytes_received # => 1024000
interface.total.bytes_sent # => 2048000
interface.total.bytes_transmitted # => 3072000
```
##### By Month
```ruby
interface.months # => #
```
```ruby
interface.months.first
interface.months[2015, 9]
# => #
```
```ruby
interface.months[2015, 10].bytes_received # => 3072000
```
##### By Day
```ruby
interface.days # => #
```
```ruby
interface.days.first
interface.days[Date.new(2015, 11, 23)]
interface.days[2015, 11, 23]
# => #, ...>
```
```ruby
interface.days[2015, 11, 23].bytes_received # => 2048000
```
##### By Hour
```ruby
interface.hours # => #
```
```ruby
interface.hours.first
interface.hours[Date.new(2015, 9, 22), 10]
interface.hours[2015, 9, 22, 10]
# => #, hour: 10>
```
```ruby
interface.hours[2015, 9, 22, 10].bytes_received # => 2048000
```
##### Tops
```ruby
interface.tops #=> #
interface.tops.count #=> 10
interface.tops.each do |top|
# ...
end
```
```ruby
interface.tops.first
interface.tops[2]
# => #
```
```ruby
interface.tops[1].bytes_received # => 1024000
```
### Contributing to vnstat-ruby
* Check out the latest master to make sure the feature hasn't been implemented
or the bug hasn't been fixed yet.
* Check out the issue tracker to make sure someone already hasn't requested it
and/or contributed it.
* Fork the project.
* Start a feature/bugfix branch.
* Commit and push until you are happy with your contribution.
* Make sure to add tests for it. This is important so I don't break it in a
future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to
have your own version, or is otherwise necessary, that is fine, but please
isolate to its own commit so I can cherry-pick around it.
### Copyright
Copyright (c) 2015-2020 Tobias Casper. See LICENSE.txt for further details.