Documentation matters or why OSMC made me write NSClient++ API docs

Last year I learned about the new HTTP API in NSClient++. I stumbled over it in a blog post with some details, but there were no docs. Instant thought “a software without docs is crap, throw it away”. I am a developer myself, and I know how hard it is to put your code and features into the right shape. And I am all for Open Source, so why not read the source code and reverse engineer the features.

I’ve found out many things, and decided to write a blog post about it. I just had no time, and the old NSClient++ documentation was written in ASCIIDoc. A format which isn’t easy to write, and requires a whole lot knowledge to format and generate readable previews. I skipped it, but I eagerly wanted to have API documentation. Not only for me when I want to look into NSClient++ API queries, but also for anyone out there.

 

Join the conversation

I met Michael at OSMC 2016 again, and we somehow managed to talk about NSClient++. “The development environment is tricky to setup”, I told him, “and I struggle with writing documentation patches in asciidoc.”. We especially talked about the API parts of the documentation I wanted to contribute.

So we made a deal: If I would write documentation for the NSClient++ API, Michael will go for Markdown as documentation format and convert everything else. Michael was way too fast in December and greeted me with shiny Markdown. I wasn’t ready for it, and time goes by. Lately I have been reviewing Jean’s check_nscp_api plugin to finally release it in Icinga 2 v2.7. And so I looked into NSClient++, its API and my longstanding TODO again.

Documentation provides facts and ideally you can walk from top to down, and an API provides so many things to tell. The NSClient API has a bonus: It renders a web interface in your browser too. While thinking about the documentation structure, I could play around with the queries, online configuration and what not.

 

Write and test documentation

Markdown is a markup language. You’ll not only put static text into it, but also use certain patterns and structures to render it in a beautiful representation, just like HTML.

A common approach to render Markdown is seen on GitHub who enriched the original specification and created “GitHub flavoured Markdown“. You can easily edit the documentation online on GitHub and render a preview. Once work is done, you send a pull request in couple of clicks. Very easy 🙂

If you are planning to write a massive amount of documentation with many images added, a local checkout of the git repository and your favourite editor comes in handy. vim handles markdown syntax highlighting already. If you have seen GitHub’s Atom editor, you probably know it has many plugins and features. One of them is to highlight Markdown syntax and to provide a live preview. If you want to do it in your browser, switch to dillinger.io.

NSClient++ uses MKDocs for rendering and building docs. You can start an mkdocs instance locally and test your edits “live”, as you would see them on https://docs.nsclient.org.

Since you always need someone who guides you, the first PR I sent over to Michael was exactly to highlight MKDocs inside the README.md 🙂

 

Already have a solution in mind?

Open the documentation and enhance it. Fix a typo even and help the developers and community members. Don’t move into blaming the developer, that just makes you feel bad. Don’t just wait until someone else will fix it. Not many people love to write documentation.

I kept writing blog posts and wiki articles as my own documentation for things I found over the years. I once stopped with GitHub and Markdown and decided to push my knowledge upstream. Every time I visit the Grafana module for Icinga Web 2 for example, I can use the docs to copy paste configs. Guess what my first contribution to this community project was? 🙂

I gave my word to Michael, and you’ll see how easy it is to write docs for NSClient++ – PR #4.

 

Lessions learned

Documentation is different from writing a book or an article in a magazine. Take the Icinga 2 book as an example: It provides many hints, hides unnecessary facts and pushes you into a story about a company and which services to monitor. This is more focussed on the problem the reader will be solving. That does not mean that pure documentation can’t be easy to read, but still it requires more attention and your desire to try things.

You can extend the knowledge from reading documentation by moving into training sessions or workshops. It’s a good feeling when you discuss the things you’ve just learned at, or having a G&T in the evening. A special flow – which I cannot really describe – happens during OSMC workshops and hackathons or at an Icinga Camp near you. I always have the feeling that I’ve solved so many questions in so little time. That’s more than I could ever write into a documentation chapter or into a thread over at monitoring-portal.org 🙂

Still, I love to write and enhance documentation. This is the initial kickoff for any howto, training or workshop which might follow. We’re making our life so much easier when things are not asked five times, but they’re visible and available as URL somewhere. I’d like to encourage everyone out there to feel the same about documentation.

 

Conclusion

Ever thought about “ah, that is missing” and then forgot to tell anyone? Practice a little and get used to GitHub documentation edits, Atom, vim, MkDocs. Adopt that into your workflow and give something back to your open source project heroes. Marianne is doing great with Icinga 2 documentation already! Once your patch gets merged, that’s pure energy, I tell you 🙂

I’m looking forward to meet Michael at OSMC 2017 again and we will have a G&T together for sure. Oh, Michael, btw – you still need to join your Call for Papers. Could it be something about the API with a link to the newly written docs in the slides please? 🙂

PS: Ask my colleagues here at NETWAYS about customer documentation I keep writing. It simply avoids to explain every little detail in mails, tickets and whatnot. Reduce the stress level and make everyone happy with awesome documentation. That’s my spirit 🙂

Michael Friedrich

Autor: Michael Friedrich

Michael ist seit vielen Jahren Icinga Developer und hat sich Ende 2012 in das Abenteuer NETWAYS gewagt. Ein Umzug von Wien nach Nürnberg mit der Vorliebe, österreichische Köstlichkeiten zu importieren - so mancher Kollege verzweifelt an den süchtig machenden Dragee-Keksi. Oder schlicht am österreichischen Dialekt der gerne mit Thomas im Büro intensiviert wird ("Jo eh."). Wenn sich Michael mal nicht im Monitoring-Portal helfend meldet, arbeitet er am nächsten LEGO-Projekt oder geniesst das schöne Nürnberg. Oder - at an Icinga Camp near you 😉

PHP Error – php_network_getaddresses

Ein Problem zu dem es viele Lösungsansätze gibt, ist folgender PHP Fehler. Er tritt beispielsweise auf, beim Verbinden auf externe Anwendungen oder APIs:
php_network_getaddresses: getaddrinfo failed: No address associated with hostname

Im Netz kursieren Teilweise die wildesten Lösungsansätze. Da ich vor kurzem mit eben diesem Problem konfrontiert wurde, möchte ich meine Erfahrung mit euch teilen. In der “php.ini” gibt es einen Parameter, der diesen Fehler verursachen kann.

Dieser kann unterschiedlich gefüllt sein und ist per default leer.

disable_functions = pcntl_alarm,pcntl_fork,,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,,pcntl_signal,,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,,pcntl_exec,pcntl_getpriority,pcntl_setpriority

Um obigen Fehler zu beheben, kann es also reichen, sich diesen Parameter anzusehen und notfalls sogar komplett zu leeren.

Marius Gebert

Autor:

Marius ist seit September 2013 bei uns beschäftigt. Er hat im Sommer 2016 seine Ausbildung zum Fachinformatiker für Systemintegration absolviert und kümmert sich nun um den Support unserer Hostingkunden. Seine besonderen Themengebiete erstrecken sich vom Elastic-Stack bis hin zu Puppet. Auch an unserem Lunchshop ist er ständig zu Gange und versorgt die ganze Firma mit kulinarischen Köstlichkeiten. Seine Freizeit verbringt Marius gern an der frischen Luft und wandert dabei durch die fränkische Schweiz

Monthly Snap May < GitLab CE, Icinga 2, NWS, OSDC, Ubuntu, Graphite, Puppet, SuiteCRM

In May, Achim started with GitLab CE, while Florian presented Vanilla.
Then, Lennart wrote the fifth part of his Icinga Best Practices and Isabel told us about the MultiTech MTD-H5-2.0.
Martin K. continued with external monitoring of websites and services with Icinga 2 while Julia gave a triple hurray to our OSDC-sponsors. Stefan G. gave an insight in his „Mission Loadbalancer Upgrade“ and Blerim tested Ruby applications with RSpec and WebMock.
Lennart published part 3 and 4 of „Icinga 2 – Automated Monitoring with Puppet“, Martin K. showed the benefits of our SuiteCRM Hosting while Marius G. told us the upcoming death of Ubuntu Unity.
May went on with the OSDC in Berlin and the reports from Isabel, Julia, Michi and Dirk.
Then Thomas Widhalm continued with the Carbon Relay for Graphite and Christian wrote about the Icinga 2 Satellite in NWS.
Towards the end of May, Christian announced some new webinars and Gabriel gave an insight in his work at NETWAYS!

Julia Hackbarth

Autor: Julia Hackbarth

Julia ist seit 2015 bei NETWAYS. Sie hat im September ihre Ausbildung zur Kauffrau für Büromanagement gestartet. Etwas zu organisieren macht ihr großen Spaß und sie freut sich auf vielseitige Herausforderungen. In ihrer Freizeit spielt Handball eine große Rolle: Julia steht selbst aktiv auf dem Feld, übernimmt aber auch gerne den Part als Schiedsrichterin.

Monthly Snap April > NETWAYS Web Services, Braintower, OSBConf, Teamweekend, AKCP, OSDC, GitLab CE, Galera, GitHub, Puppet

In April, Isabel startet with announcing a new Software Update for Braintower and Martin K. continued with a new NETWAYS Web Services tool: Rocket.Chat Hosting.

Then Julia announced the call for papers for the Open Source Backup Conference 2017 in Cologne while Marius wrote about the end of Ubuntu 12.04 LTS.

Later in April, Marius H. gave some practical tips for the Galera Cluster and Dirk wrote about contributing to projects on GitHub.

Then Martin K. presented the next NETWAYS Web Services App, GitLab CE Hosting, and Julia told about the latest OSDC-News.

Furthermore, Catharina reviewed the team event of the commercial departments while Noah told us how to block some Google searches in Google Chrome.

Lennart gave an insight in the monitoring project at htp GmbH and Daniel introduced himself.

Towards the end of April, Isabel told about the latest news concerning the AKCP sensorProbe 2+ and Martin S. explained external monitoring by the Icinga2 satellites at NETWAYS Web Services.

Last but not least, Jean reported on monitoring powershell scripts with Icinga 2, while Lennart went on with part 2 of automated monitoring with Puppet.

Julia Hackbarth

Autor: Julia Hackbarth

Julia ist seit 2015 bei NETWAYS. Sie hat im September ihre Ausbildung zur Kauffrau für Büromanagement gestartet. Etwas zu organisieren macht ihr großen Spaß und sie freut sich auf vielseitige Herausforderungen. In ihrer Freizeit spielt Handball eine große Rolle: Julia steht selbst aktiv auf dem Feld, übernimmt aber auch gerne den Part als Schiedsrichterin.

Ruby Applikationen testen mit RSpec und WebMock

Das Testen von Software begleitet mich von Projekt zu Projekt. Bei bisherigen Entwicklungen habe ich immer wieder auf RSpec zurück gegriffen, ein tool zum testen von Ruby Applikationen. Es zeichnet sich durch eine relativ einfache Handhabung aus und eine Ausdrucksweise die an die menschliche Sprache angelehnt ist. Auch wenn nicht jeder mögliche einzutretende Fall getestet werden kann, tests geben Entwicklern Sicherheit wenn Änderungen am Code vorgenommen werden.

WebMock

WebMock ist eine Library die es einem ermöglich HTTP requests auszudrücken und Erwartungen an diese zu setzen. In Verbindung mit RSpec lässt sich WebMock verwenden um eine Ruby Anwendung zu testen die HTTP Requests ausführt, beispielsweise an eine API. Oft sind diese Requests nicht starr sondern werden dynamisch anhand von Parametern zusammen gesetzt. WebMock/RSpec hilft dabei unterschiedliche Fälle zu simulieren, Erwartungen zu definieren und diese mit zu prüfen.

WebMock ist als Gem verfügbar, die Installation ist daher relativ einfach:

user@localhost ~ $ gem install webmock

Als Beispiel verwende ich eine sehr simple Ruby Klasse. Deren einzige Methode ‘request’ sendet einen GET request an die URL ‘https://wtfismyip.com’. Abhängig vom Parameter ‘option’ wird die IP entweder in Textform oder als JSON abgefragt:

require 'net/http'
require 'uri'

class ApiCaller
  def self.request(option)
    uri = URI.parse("https://wtfismyip.com/#{option}")
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    request = Net::HTTP::Get.new(uri.request_uri)
    http.request(request)
  end
end

Mein Test beinhaltet den Aufruf der ‘request’ Methode. Der HTTP request wird simuliert und die Erwartung das ein Request an eine bestimmte URL stattfinden soll wird auch definiert.

require 'api_caller'
require 'webmock/rspec'

describe ApiCaller do
  describe '.request' do
    context 'given json parameter' do
      it 'requests json url' do
        stub_request(:get, 'https://wtfismyip.com/json')
        expect(ApiCaller.request('json')).
          to have_requested(:get, 'https://wtfismyip.com/json').once
      end
    end

    context 'given text parameter' do
      it 'requests text url' do
        stub_request(:get, 'https://wtfismyip.com/text')
        expect(ApiCaller.request('text')).
          to have_requested(:get, 'https://wtfismyip.com/text').once
      end
    end
  end
end

Beim testen sieht das nun folgendermaßen aus:

user@localhost ~ $ rspec --format documentation

ApiCaller
  .request
    given json parameter
      requests json url
    given text parameter
      requests text url

Finished in 0.00557 seconds (files took 0.37426 seconds to load)
2 examples, 0 failures
Blerim Sheqa

Autor: Blerim Sheqa

Blerim ist seit 2013 bei NETWAYS und seitdem schon viel in der Firma rum gekommen. Neben dem Support und diversen internen Projekten hat er auch im Team Infrastruktur tatkräftig mitgewirkt. Hin und wieder lässt er sich auch den ein oder anderen Consulting Termin nicht entgehen. Mittlerweile kümmert sich Blerim hauptsächlich im Icinga Umfeld um die technischen Partner und deren Integrationen in Verbindung mit Icinga 2.

Kampf den nutzlosen Menu Bar Icons (macOS)

Tools auf dem Mac gibt es mittlerweile wie Sand am Meer. Große oder kleine praktische Apps, welche die Arbeit erleichtern oder Aufgaben automatisieren. Viele haben einige dieser Systemwerkzeuge wie z.B. Alfred installiert, weil es das Arbeiten angenehmer macht.

Leider nutzen viele dieser Werkzeuge die Möglichkeit, um sich in der Menüleiste von macOS zu verewigen. Bei einigen macht es durchaus Sinn – und natürlich hängt dies auch vom Geschmack des Nutzers ab. Allerdings bieten die meisten davon aus meiner Erfahrung keinen richtigen Mehrwert.

Bisher gibt es keine Out of the box Möglichkeit, diesen Exzess einzudämmen. Zwar kann man viele der System-Icons einfach ausblenden, aber viele 3rd-Party Icons sind sehr hartnäckig, wenn sie denn keine Option zum Deaktivieren des Icons implementiert haben.

Abhilft schafft … ein weiteres Tool

 

Vanilla Demo

Vorher – Nachher: Mit Vanilla lassen sich selten genutzte Menüleisten-Icons ein und ausblenden.

Vor kurzem habe ich ein kleines Helferlein namens Vanilla gefunden, welches den User unnötige oder nicht genutzte Icons ausblenden lässt (es gibt auch eine Pro-Version, mit der man die Icons komplett ausblenden kann). Das bringt wieder etwas Übersicht in die Menüleiste zurück.

 

Florian Strohmaier

Autor: Florian Strohmaier

Mit seinen Spezialgebieten UI-Konzeption, Prototyping und Frontendentwicklung unterstützt Florian das Dev-Team bei NETWAYS. Trotz seines Design-Backgrounds fühlt er sich auch in der Technik zuhause. Gerade die Kombination aus beidem hat für ihn einen besonderen Reiz.