Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add system information #17

Merged
merged 9 commits into from
Jun 16, 2019
Merged

Add system information #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ab6192f
:heavy_plus_sign: add gopsutil dependencies
l4u23n7p Jun 16, 2019
10cd27f
:sparkles: add errors pkg
l4u23n7p Jun 16, 2019
bbf3a7d
:sparkles: add agent pkg
l4u23n7p Jun 16, 2019
5fe7bf5
:sparkles: add info pkg
l4u23n7p Jun 16, 2019
a5f7672
:package: update main.go
l4u23n7p Jun 16, 2019
2eef4ec
:rocket: change application ports
l4u23n7p Jun 16, 2019
7c31a83
:white_check_mark: add test helper commands
l4u23n7p Jun 16, 2019
828c5b2
:fire: removed unused directory
l4u23n7p Jun 16, 2019
202e364
:pencil: add usage documentation
l4u23n7p Jun 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@

# Output of the go coverage tool, specifically when used with LiteIDE
*.out
coverage.html

# Certificate files
*.key
Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@ WORKDIR /app
COPY . .
RUN make test
RUN make build
EXPOSE 8080 9090
EXPOSE 4455 5544
CMD ["./bin/boxmetrics-agent"]
11 changes: 10 additions & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.PHONY: run test build clean cert rootca
.PHONY: run test coverage build clean cert rootca

run:
@echo "Starting module"
Expand All @@ -8,6 +8,15 @@ test:
@echo "Running module test"
go test -v ./...

coverage:
@echo "Running coverage"
go test -v -cover ./...

coverage-html:
@echo "Running coverage html"
go test -cover -coverprofile=c.out ./...
go tool cover -html=c.out -o coverage.html

build:
@echo "Building module to ./bin"
mkdir -p bin
Expand Down
169 changes: 142 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,48 +4,164 @@

## 📦 Requirements

> Only if you want to run the source code
> Not needed if you run from a prebuilt binary

This project should be working as expected with the following minimal version of:

| Dependency | Version |
| ---------- | :------: |
| Go | >= v1.11 |

The project might be working with older version of Go, if you add vendor directory with `go mod vendor` command _(available from Go 1.11)_. Since this repo is based on go modules dependencies, the vendor directory won't be add, it's your own choice if you want it.
| ---------- | -------- |
| Go | >= v1.12 |

## 🚀 Quick start

### _From prebuilt binaries :_

1. **Donwload a binary from Github [release page](https://github.com/boxmetrics/boxmetrics-agent/releases)**

2. **Run application**

```bash
# Made application executable
sudo chmod +x boxmetrics-agent

# Start application
./boxmetrics-agent
```

### _From source code :_

1. **Clone the git repository**

```bash
# cloning git repository
git clone https://github.com/boxmetrics/boxmetrics-agent
```bash
# cloning git repository
git clone https://github.com/boxmetrics/boxmetrics-agent
```

cd boxmetrics-agent
```
2. **Build application**

2. **Run application**
```bash
# go to boxmetrics-agent directory
cd boxmetrics-agent
# run helper command to build
make build
```

3. **Run application**

```bash
# Made application executable
sudo chmod +x bin/boxmetrics-agent

# Start application
./bin/boxmetrics-agent
```

## 💡 Usage

### Routes

| Path | Description |
| -------- | -------------- |
| `/ws/v1` | Websocket root |
| `/` | Test page |

### Communication

Both request and response are JSON message

**Dev Version**
#### Request

| Key | Type | Require | Default | Description |
| ------- | ------- | ------- | ---------------------- | ---------------- |
| type | string | yes | NA | Request type |
| value | string | yes | NA | Type value |
| options | object | no | Default Options Object | Request options |
| format | boolean | no | true | Enable formating |

##### Type Values

| Value | Description |
| ------- | -------------------------------------------------------------- |
| info | Return `value` information type |
| script | Run `value` script |
| command | Execute `value` as command _(Use `options` to add parameters)_ |

##### Info Type Values

| Value | Response | Description |
| ------------ | ---------------------------------------------- | ------------------------------------------------------------- |
| memory | [Schema](docs/schema/memory.md#memory) | Return memory information |
| cpu | [Schema](docs/schema/cpu.md#cpu) | Return cpu usage information |
| cpuinfo | [Schema](docs/schema/cpu.md#cpu-hardware-info) | Return cpu hardware information |
| disks | [Schema](docs/schema/disk.md#disk) | Return disks information |
| containers | [Schema](docs/schema/container.md#container) | Return containers full information |
| containersid | Array of string | Return containers ID list |
| host | [Schema](docs/schema/host.md#host) | Return host information |
| users | [Schema](docs/schema/host.md#users) | Return users list |
| network | [Schema](docs/schema/network.md#network) | Return network information |
| connections | [Schema](docs/schema/network.md#connection) | Return opened connections list |
| processes | [Schema](docs/schema/process.md#process-light) | Return processes information list |
| process | [Schema](docs/schema/process.md#process) | Return process full information _(`options.pid` must be set)_ |
| general | [Schema](docs/schema/general.md) | Return system wide informations |

##### Script Type Values

No script available yet

##### Options Object

| Key | Type | Require | Default | Description |
| ---- | ------ | ------- | ------- | ------------------------------------------------------------------------------ |
| args | Array | no | null | Array of arguments to pass to the command |
| env | Array | no | null | Array of environment variable to add before executing command _eg. MY_VAR=abc_ |
| pwd | string | no | "" | Location where the command run, if empty string run in the cwd of the process |
| pid | number | no | 0 | PID use to retrieve information with `process` info type |

#### Response

| Key | Type | Description |
| --------- | ------ | --------------------------------------------------------------------------------- |
| event | object | The event send |
| data | object | The data reponse of the event. Corresponding to a specific [schema](docs/schema/) |
| startDate | string | Start date of the response processing |
| endDate | string | End date of the response processing |
| duration | string | Duration of the response processing |
| status | object | Status of the response |
| error | string | Error message _(`null` if no error)_ |

##### Status object

| Key | Type | Description |
| ------- | ------ | -------------- |
| code | number | Status code |
| message | string | Status message |

## 💬 Contributing

1. **Fork the git repository**

2. **Create your feature branch**

3. **Apply your changes**

4. **Run application**

```bash
# run test
make test
# start application in dev mode
make run
```

```bash
# start the app
make run
```
5. **Open browser to test your change!**

**Prod Version**
> Project is running at <http://localhost:4455> or <https://localhost:5544>

```bash
# build the app
make build
# run executable
./bin/boxmetrics-agent
```
6. **Commit your changes**

3. **Open browser and start editing files!**
7. **Push it on your fork**

> Project is running at <http://localhost:8080> or <https://localhost:9090>
8. **Create new pull request**

## 🧐 What's inside ?

Expand All @@ -56,16 +172,15 @@ The project might be working with older version of Go, if you add vendor directo
├── certificates # Project Certificates
├── cmd # Main applications for this project
├── configs # Configuration file templates or default configs
├── deployments # Deployment configurations and templates (docker-compose, kubernetes/helm)
├── docs # Design and user documents
├── init # System init and process manager/supervisor configs
├── internal
│ ├── app # Private application
│ └── pkg # Private library code
├── pkg # Public library code
├── scripts # Scripts to perform various build, install, analysis, etc operations
├── test # Additional external test apps and test data
├── web # Web application specific components
├── Dockerfile # Docker image
├── go.mod # Module dependencies
├── go.sum # Ensure dependencies integrity
├── JenkinsFile # Jenkins pipeline
Expand Down
Empty file removed deployments/.gitkeep
View file
Open in desktop
Empty file.
59 changes: 59 additions & 0 deletions docs/schema/container.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Response Schema for Container informations

## Container

| Key | Type | Description |
| ----------- | ------- | --------------------------------------------------------------------- |
| containerId | string | Container indentifier |
| name | string | Container string |
| image | string | Container image |
| status | string | Container status |
| running | boolean | True when up, false otherwise |
| cpu | object | Container cpu usage, see [container cpu stat](#container-cpu-stat) |
| memory | object | Container memory usage, see [container mem stat](#container-mem-stat) |

### Container CPU Stat

| Key | Type | Description |
| ------- | ------ | --------------------------------------- |
| percent | string | Container CPU usage in % |
| times | object | A [cpu time](./cpu.md#cpu-times) object |

### Container Mem Stat

| Key | Type | Description |
| ----------------------- | ------ | ------------------------------------------ |
| containerId | string | Container identifier |
| cache | string | Cache used |
| rss | string | Number of rss |
| rssHuge | string | Number of rss huge |
| mappedFile | string | Number of mapped file |
| pgpgin | string | Number of page-ins |
| pgpgout | string | Number of page-outs |
| pgfault | string | Number of page faults |
| pgmajfault | string | Number of major page faults |
| inactiveAnon | string | Number of inactive anonymous memory |
| activeAnon | string | Number of active anonymous memory |
| inactiveFile | string | Number of inactive cache memory file |
| activeFile | string | Number of active cache memory file |
| unevictable | string | Amount of memory that cannot be reclaimed |
| hierarchicalMemoryLimit | string | Maximum RAM available in the host |
| totalCache | string | Total of cache |
| totalRss | string | Total of rss |
| totalRssHuge | string | Total of rss huge |
| totalMappedFile | string | Total of mapped file |
| totalPgpgin | string | Total of page-ins |
| totalPgpgout | string | Total of page-outs |
| totalPgfault | string | Total of page faults |
| totalPgmajfault | string | Total of major page faults |
| totalInactiveAnon | string | Total of inactive anonymous memory |
| totalActiveAnon | string | Total of active anonymous memory |
| totalInactiveFile | string | Total of inactive cache memory file |
| totalActiveFile | string | Total of active cache memory file |
| totalUnevictable | string | Total of unevictable memory |
| memUsage | string | Amount of memory used |
| memMaxUsage | string | Amount of maximun memory usable |
| memoryLimit | string | Amount of physical memory that can be used |
| memoryFailcnt | string | Amount of overload memory |

More info on [docker docs](https://docs.docker.com/v17.09/engine/admin/runmetrics/#metrics-from-cgroups-memory-cpu-block-io)
57 changes: 57 additions & 0 deletions docs/schema/cpu.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Response Schema for CPU informations

## CPU

| Key | Type | Description |
| ----- | ------ | ------------------------------------------------ |
| count | object | Number of processor. See [cpu count](#cpu-count) |
| info | Array | Array of [cpu info](#cpu-info) |

### CPU Count

| Key | Type | Description |
| -------- | ------ | ---------------------------- |
| physical | string | Number of physical processor |
| logical | string | Number of logical processor |

### CPU Info

| Key | Type | Description |
| ------- | ------ | -------------------------------- |
| id | string | A CPU ID |
| percent | string | Usage of the CPU in % |
| times | object | A [cpu times](#cpu-times) object |

### CPU Times

| Key | Type | Description |
| --------- | ------ | -------------------------------------- |
| user | string | Amounts of time of the user work |
| system | string | Amounts of time of the system work |
| idle | string | Amounts of time of the idle work |
| nide | string | Amounts of time of the nice work |
| iowait | string | Amounts of time of the iowait work |
| irq | string | Amounts of time of the irq work |
| softirq | string | Amounts of time of the softirq work |
| steal | string | Amounts of time of the steal work |
| guest | string | Amounts of time of the guest work |
| guestNice | string | Amounts of time of the guest nice work |
| total | string | Total of time for all kinds of work |

## CPU Hardware Info

| Key | Type | Description |
| ---------- | ------ | ------------------------ |
| cpu | number | CPU Identifier |
| vendorId | string | Vendor Identifier |
| family | string | Family of the CPU |
| model | string | Model name |
| stepping | number | ??? |
| physicalId | string | Hardware Identifier |
| coreId | string | Something about core |
| cores | number | Number of cores |
| modelName | string | Another model name |
| mhz | number | CPU frequency |
| cacheSize | number | Cache size |
| flags | Array | Flags support by the CPU |
| microcode | string | Microcode info |
Loading