Skip to content

Latest commit

 

History

History
141 lines (107 loc) · 4.71 KB

CONTRIBUTING.md

File metadata and controls

141 lines (107 loc) · 4.71 KB

Contributing Instructions

Pull the project.

git clone https://github.com/pganalyze/collector

Make sure you have gcc installed and in your $PATH: parts of the collector's dependencies rely on cgo and will be skipped if a C compiler is not available, causing the collector build to fail.

Setup

The dependencies are stored in the vendor folder, so no installation is needed.

Updating dependencies

go get github.com/shirou/gopsutil@latest # updates the version requirement
make vendor                              # updates the vendored code

Compiling and running tests

To compile the collector and helper binaries:

make build

After building the collector you can find the binary in the repository folder:

./pganalyze-collector --help

To run the unit tests:

make test

To run the integration tests:

make integration_test

Note the integration tests require Docker, and will take a while to run through.

Test receiving Postgres logs over syslog

The ability to receive Postgres logs over syslog is not covered by automated tests. To test this manually, you'll need to relay the Postgres logs through a syslog daemon.

Here's one way to do that (assuming a locally running Postgres on a Debian/Ubuntu system):

  • sudo apt install rsyslog
  • edit your Postgres config file and set log_destination to syslog
  • add the following rsyslog configuration file at /etc/rsyslog.d/51-postgres.conf: 
    if $programname == 'postgres' then {
  *.* action(
    type="omfwd"
    StreamDriver="ptcp"
    StreamDriverMode="0"
    template="RSYSLOG_SyslogProtocol23Format"
    target="localhost" port="5514" protocol="tcp"
    action.resumeRetryCount="100"
    queue.type="linkedList" queue.size="10000"
  )
}
    you can pick another port if 5514 is not available
  • sudo service rsyslog restart
  • update your local collector configuration to monitor your local Postgres
  • update the configuration to add db_log_syslog_server = 0.0.0.0:5514 (or whatever port you selected above)
  • start the collector
  • run SELECT pg_reload_conf() in Postgres

The collector should now be receiving Postgres logs via rsyslog.

Build the Helm Docs

The Helm chart README.md file is generated by helm-docs. To ensure that the documentation remains up-to-date, regenerate the README.md file using the helm-docs command whenever you make changes to the Helm chart or prior to making a new release.

You can either install helm-docs locally, or run using Docker:

$ docker run --rm --volume "$(pwd):/helm-docs" -u "$(id -u)" jnorwood/helm-docs:latest
time="2024-04-26T02:01:07Z" level=info msg="Found Chart directories [contrib/helm/pganalyze-collector]"
time="2024-04-26T02:01:07Z" level=info msg="Generating README Documentation for chart contrib/helm/pganalyze-collector

Release

  1. Create a PR to update the version numbers and CHANGELOG.md
  2. Once PR is merged, create a new tag git tag v0.x.y, then push it git push origin v0.x.y
  3. Once a new tag is pushed, GitHub Action Release will be kicked and create a new release (this will take about 2 hours, due to the package build and test)
  4. Modify the newly created release's description to match to CHANGELOG.md
  5. Release docker images using make docker_release (this requires access to the Quay.io push key, as well as "docker buildx" with QEMU emulation support, see below)
  6. Sign and release packages using make -C packages repo (this requires access to the Keybase GPG key)

To run step 5 from an Ubuntu 22.04 VM, do the following:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin

# Add support for ARM emulation
sudo apt update
sudo apt install qemu-user-static binfmt-support make

# Get these credentials from Quay.io
sudo docker login -u="REPLACE_ME" -p="REPLACE_ME" quay.io

git clone https://github.com/pganalyze/collector.git
cd collector
sudo make docker_release