Chapter 10. Logging

JSON

You can create a simple json logfile with PHPBU's json logger.

Example 10.1: json XML example

<!-- create a json logfile -->
<log type="json" target="backup/log.json"/>


Example 10.2: json JSON example

{"type": "json", "target": "backup/log.json"}


E-Mail

PHPBU uses SwiftMailer to send backup reports to one or more configured email addresses. If you just want to get notified if something went wrong, you can use the sendOnlyOnError option to not send any email on a successful backup.

Table 10.1. Email-Options

NameValueRequiredDefaultDescription
recipientsstringyes-List of emails separated by semicolon.
sendOnlyOnErrorstringnofalseSending reports only if something goes wrong.
subjectstringnoPHPBU Backup Report from $HOSTNAMEEmail subject of the backup report.
transportstringyes-SwiftMailer Transport that's used to send the email (mail, sendmail, smtp, null).
sender.mailstringphpbu@hostname-The sender email address
sender.namestringnoOS-UserThe sender name.
sender.namestringnoOS-UserThe sender name.
sendmail options    
sendmail.pathstringno-Path to local sendmail binary.
sendmail.optionsstringno-Sendmail options (e.g. -bs).
SMTP options    
smtp.portstringno25Port to use to connect to SMTP server.
smtp.hoststringno-SMTP hostname.
smtp.usernamestringno-The SMTP login.
smtp.passwordstringno-The SMTP password.
smtp.encryptionstringno-Type of encryption (e.g. ssl).


Example 10.3: mail XML example

<!-- use mail to keep up to date with your backup creation -->
<log type="mail">
  <option name="transport" value="mail"/>
  <option name="recipients" value="user.name@example.com"/>
</log>


Example 10.4: mail JSON example

{
  "type": "mail",
  "options": {
     "transport": "mail",
     "recipients": "user.name@example.com"
   }
}


Telegram

You can log to a Telegram group or contact.

Table 10.2. Telegram-Options

NameValueRequiredDefaultDescription
chat_idstringyes-Telegram chat ID
bot_idstringno-Telegram bot ID.
bot_tokenstringno-Telegram bot authentication token.


Example 10.5: Telegram XML example

<!-- write to Telegram chat -->
<log type="telegram">
  <option name="chat_id" value="YOUR_CHAT_ID"/>
  <option name="bot_id" value="YOUR_BOT_ID"/>
  <option name="bot_token" value="YOUR_BOT_TOKEN"/>
</log>


Example 10.6: Telegram JSON example

{
  "type": "telegram",
  "options": {
     "chat_id": "YOUR_CHAT_ID",
     "bot_id": "YOUR_BOT_ID",
     "bot_token": "YOUR_BOT_TOKEN"
   }
}


Webhook

You can call a webhook and PHPBU will send report data to the webhook.

Table 10.3. Webhook-Options

NameValueRequiredDefaultDescription
uristringno-URI to call
usernamestringno-Basic auth user name.
passwordstringno-Basic auth password.
methodstringnogetHTTP request method (get, post).
contentTypestringnoapplication/jsonPost method request body content type.
templatestringno-A template to use for the request body For example if you want to you xml over json.
timeoutintegerno-How long until the request times out (seconds)


Example 10.7: webhook XML example

<!-- call webhook -->
<log type="webhook">
  <option name="uri" value="http://example.com/hook"/>
</log>


Example 10.8: webhook JSON example

{
  "type": "webhook",
  "options": {
     "uri": "http://example.com/hook"
   }
}


If you change the request method to post by default you will receive a request body in the following format.

Example 10.9: Default request body example

{
  "status": 0,
  "timestamp": 12783781381,
  "duration": 234.3402,
  "backupCount": 1,
  "backupFailed": 0,
  "errorCount": 0,
  "errors": [],
  "backups": [
    {
      "name":
      "status":
      "checks": {
          "executed": 1,
          "failed": 0,
      },
      "crypt": {
          "executed": 1,
          "skipped": 0,
          "failed": 0,
      },
      "syncs" => {
          "executed": 1,
          "skipped": 0,
          "failed": 0
      },
      "cleanup" => {
          "executed": 1,
          "skipped": 0,
          "failed": 0
      }
    }
  ]
}


If this format doesn't work for you, you can define your own request body with a template.

Example 10.10: Template example

<?xml version="1.0" encoding="UTF-8"?>
<report>
  <status>%status%</status>
  <date>%timestamp%</date>
  <backups>
    %%backup%%
    <backup>
      <name>%name%</name>
      <status>%status%</status>
    </backup>
    %%backup%%
  </backups>
  <errors>
    %%error%%
    <error class="%class%" message="%message%" file="%file%" line="%line%" />
    %%error%%
  </errors>
</report>


Prometheus

You can create a file containing meta data which can be consumed by Prometheus.

Example 10.11: Prometheus XML example

<!-- call prometheus -->
<log type="prometheus">
  <option name="target" value="backup/log.prom"/>
</log>


Example 10.12: Prometheus JSON example

{
  "type": "prometheus",
  "target": "backup/log.prom"
}


Example 10.13: Example output

# HELP phpbu_backup_success Whether or not the backup succeeded
# TYPE phpbu_backup_success gauge
phpbu_backup_success{name="backupName0"} 1
phpbu_backup_success{name="backupName1"} 0

# HELP phpbu_backup_duration The total time the backup took to execute
# TYPE phpbu_backup_duration gauge
phpbu_backup_duration{name="backupName0} 10.14783922
phpbu_backup_duration{name="backupName1} 166.72893933

# HELP phpbu_backup_last_run The unix timestamp of the last run
# TYPE phpbu_backup_last_run counter
phpbu_backup_last_run{name="backupName0} 1586983854
phpbu_backup_last_run{name="backupName1} 1586985773

# HELP phpbu_backup_size The size of the last successful backup
# TYPE phpbu_backup_size gauge
phpbu_backup_size{name="backupName0} 92474832
phpbu_backup_size{name="backupName1} 374893


Please open a ticket on GitHub to suggest improvements to this page. Thanks!