Logging Custom Fields
Last updated
Was this helpful?
Last updated
Was this helpful?
FLAT writes for events like client access or upstream requests. The structured log events are easily extensible.
The already provides a basic set of information about the incoming request. However, when inspecting (any) logs quickly the wish for more contextual information will arise.
Here are some ideas for fields to augment your logs with:
A random "Tab" ID sent by the client to correlate API requests to a single SPA instance
The version or git revision of your FLAT project
A message to distinguish reasons for errors
The staging role (dev/test/prod) or data center identifier passed in by
The client's real IP address as advertised by a downstream system (e.g. your load balancer)
User and Role from a
…
We want all of that!
To play with logging, you need a FLAT project. If you don't have on, yet, have a look into the to .
Before start customizing our logs, we need to setup our workplace in order to see what we are doing. Where can we inspect FLAT logs?
FLAT runs in and writes its log lines to stdout
and stderr
. (If you don't know the two, don't fear.) In a development setup, we usually start FLAT with the . If you run
However, once you call your API with curl
you will see JSON lines in your terminal:
Now, the access log will be nicely readable on your terminal:
Now that we know where our logs go, we're finally ready to add fields!
We will start with a simple task: Let's add a field to our log that contains a fixed string.
This can actually be useful: if you share a log server with other FLAT projects, the field let's you identify the originating project. (In production, your log shipper will probably provide this information already in its log envelope.)
Call your FLAT API again and watch the logs:
Our first custom log field has hit the terminal!
To include this information into the log, we add more fields to our log
action:
Notice, how we can provide default values for missing data. If both of the variables are not set, a log may look like this:
stage
is always defined. But location
is missing, because its expression has evaluated to null
. Nulled fields don't show up in the log.
Your custom log fields are not restricted to the top-level field-list. If you have more fields, that belong together, you can group them in an object.
In our case, we might want to gather information about the environment:
Clients provide a lot of useful information in the HTTP request headers. We can easily use them to augment our log:
Every API has to rely on user input for its operation. But we should do so with care. (Every client could sent a X-Forwarded-Proto
header. The administrator should take measures to override this header in the SSL offloader.)
Put this into tests/loggging.xml
:
You can run the test with this command:
In a real project, you would rather send a request to your FLAT API and check if the log was written as expected:
you will see the log output in your terminal. Some startup messages are plain text lines. The will be text, too.
You can have the JSON colored and pretty printed by piping the output to the :
Log fields can be registered with the . The action takes a as its argument. For our fixed field, we write:
A good place for this action is the because it is started for all API flows.
With you can use expressions to dynamically set field names and values.
Let's assume, you use the FLAT_STAGE
to tell your project in which deployment stage it is running. Possible values could be dev
, qa
and prod
. Another variable FLAT_DC
holds the airport code of the data center, e.g. CGN
or LON
.
Here, we use the to create log fields from headers. If present, the headers will show up in the log:
For logging alone, the JSON armor prevents format breakouts and log attacks. HTTP request headers and query strings are limited in size. However, you could use to further validate a parameter's format.
Log augmentation with the belongs to our project code. Therefore, we would like to test that! This can be done by using the in a .
(Administration)
(Reference)
(Reference)