geeksville / particleweblog

A publish based web logger for particle.io

ParticleWebLog

A Particle library for remote logging via publish(). And example config for loggly.com.

I wrote this tiny logging framework because I wanted something that would allow remote logging but use very little FLASH space.

Other benefits:

• Messages are not sent in cleartext (they are inside the particle encrypted link).
• Because this library doesn't use UDP, it is probably a more resistant to carrier throttling on cellphone networks (i.e. for the Electron)

Usage

#include "ParticleWebLog.h"
ParticleWebLog particleWebLog;

void setup() {
  Log.info("Hi I'm a log message");
}

void loop() {
}

See the examples folder for more details.

Documentation

This library merely registers a log provider that publishes each logged string as a particle publish event. The events will be published using the name of your choice (defaults to "log").

Limitations:

• This tiny library is built on top of Particle.publish, so you should not print log message too quickly if you are using it. It might drop messages if you send more than about 1 a second.
• Third generation particle devices have lots of log messages from the system some of which seem to come out before publishing is legal. So this log provider only logs "app" messages.

Using web logging services

One of the great things about this approach is that the Particle.io web service has good webhook support. So you can squirt these crude log messages to a nice storage/viewer service. Most any service that has a way to accept HTTP posts of log messages should work. Here is an example using loggly.com:

• Go to loggly.com and create a free account (you can pick any domain name).
• Go to the console for your domain: https://yourdomain.loggly.com/sources/setup/https and setup an HTTPS log source. It will give you an URL that looks approximately like this: https://logs-01.loggly.com/inputs/XXXXXXXX-76a8-4af5-a967-XXXXXXXXXXXX/tag/http/.
• Go to the Particle.io web console and click on "Integrations / New Integration / Webhook".
• On the form it shows, enter "log" for Event Name, the URL you were provided above, change the request format to JSON.
• Then click to enter custom JSON data and paste in the following:

{
  "message": "{{{PARTICLE_EVENT_VALUE}}}",
  "from": "{{{PARTICLE_DEVICE_ID}}}",
  "published_at": "{{{PARTICLE_PUBLISHED_AT}}}",
  "userid": "{{{PRODUCT_USER_ID}}}",
  "fw_version": "{{{PRODUCT_VERSION}}}"
}

• Click "save" to save your new integration.
• In the top right of the integration you should now see a "Test" button. You can click it to test that the Particle server is now able to talk with Loggly.
• Any new log publishes from your device should now be stored in Loggly.

Contributing

I will happily accept pull requests and respond to issues raised in github.

Thanks to @barakewi for his Papertrail library which was used as a template to create this library.

LICENSE

Copyright 2019 [email protected]

Licensed under the MIT license

particleweblog's Issues

Doesn't work with argon

So this lib works fine on my Photon device, but I just tried it on argon and it dies there (painful hard fault). I suspect it is a problem with the current (pretty rough argon libs), but I'll debug as soon as I work through the other problems with Argon ;-)

Using publish() in log handler is not recommended

This log handler is using Particle.publish() in the log handler function:

ParticleWebLog/src/ParticleWebLog.cpp

Line 20 in b4d1861

Particle.publish(m_name, message, PRIVATE);

Using Particle.publish() in the log handler function is not recommended:

I would recommend not doing anything that takes any time or can block from the log handler. This includes publishing, network, and any shared resource calls like SPI.
https://community.particle.io/t/udp-or-particle-publish-in-log-handler-causing-freeze-with-system-thread/56826/4

Using this log handler in combination with SYSTEM_THREAD(ENABLED) can cause freezes on 3rd gen Devices, as described in the Particle forum thread linked above.

To solve this, the logs could be saved to a buffer and the network functions moved to the main loop, as suggested and implemented by @rickkas7 in https://github.com/rickkas7/SdCardLogHandlerRK

Bug: No Check for connection made.

In the ParticleWebLog::log the Particle.publish is used to send the message. However a check is not made to check if the device is actually currently connected to the cloud, so that if the system is set to Semi or Manual mode then the Particle.publish can hang between 20Seconds and 5minutes. As detailed by the particle reference docs

If the cloud connection is turned on and trying to connect to the cloud unsuccessfully, Particle.publish may block for 20 seconds to 5 minutes. Checking Particle.connected() can prevent this.

So maybe need to add a Particle.connected() to the if statement.

particleusageweblog.ino:3:28: ParticleWebLog.h: No such file or directory

when using the "usage" example in the library on the web IDE - above error is raised