Logging in Eleventy
Eleventy uses the
debug package to log
debug messages to the console. If something is going wrong with your
build, you can set the DEBUG
environment variable to view
log messages from specific parts of Eleventy, or all of it. The
Eleventy docs refer to this as
Debug Mode.
DEBUG=Eleventy* eleventy
DEBUG=Eleventy:ComputedData eleventy
Debugging Your Own Code
Since debug
is already installed with your Eleventy
project, you might want to take advantage of it yourself to debug your
own code. All you have to do is import the debug
module
and create a logger with your namespace. For example, suppose you have
some computed data that pulls data from a database.
// Create a logger that writes to the darthmall:database namespace.
const debug = require("debug")("darthmall:database");
module.exports = async function () {
let data = [];
debug("Fetching data...");
try {
let data = await getRecords();
debug(`Fetched ${data.length} records`);
} catch {
debug("Database read failed");
}
return data;
};
Now if we need to debug our database fetch, we can run our build with
DEBUG=darthmall:database
in the environment.
DEBUG=darthmall:database eleventy
Add Your Logs to Eleventy’s
There’s just one problem with the above solution: when we set
DEBUG=darthmall:database
, all of the output from Eleventy
disappears. If you’re trying to debug some part of your site locally,
this is great because it keeps unrelated log messages out of sight.
But what if you want these logs included as part of a build—say in
CI—so that if a build fails you can go back and see the
reason. In this case, you may want to add your logs to the default
Eleventy output so that the logs in CI are more informative.
If you dig around in the
Eleventy source code, you’ll find that the default Eleventy messages are output to the
Eleventy:Logger
namespace. We can add this to our
DEBUG
environment variable with a comma and then both of
the default Eleventy log messages and our database log messages will
be printed.
DEBUG=Eleventy:Logger,darthmall:database eleventy
Et voilà! We get to see Eleventy’s usual output about writing templates and so on along with the output from our database code. This way we get nice status messages in our builds, but if something goes wrong, we don’t have to re-run the build in CI to find out what went wrong.
Beware GitLab CI
If you happen to be buiding your Eleventy site with GitLab CI, you
have to be careful about how you set your DEBUG
variable.
You might be tempted—as I was—to set it as a variable in the job.
build:
variables:
DEBUG: "Eleventy:Logger,darthmall:database"
script:
- eleventy
DEBUG
variable in GitLab CI’s environment
variable config section.
Doing this will probably break your builds. For some reason, setting a
DEBUG
variable in the job like this, causes artifact
uploads to fail as well as some other bad behaviors. There’s an
open issue for GitLab CI, which has been open for several years. Instead, you should set the
DEBUG
variable when you invoke eleventy
.
build:
script:
- DEBUG="Eleventy:Logger,darthmall:database" eleventy
DEBUG
variable just for your Eleventy
build.
This limits the scope of the DEBUG
environment variable
to just your Eleventy build process, so that when it comes time for
GitLab to upload artifacts or do any other work, the variable is not
present and everything continues to function normally.
Happy logging!