DEV Community: Vitor Oliveira

Scrum PSM I - Notes

Vitor Oliveira — Thu, 30 Apr 2020 08:08:17 +0000

Scrum Framework Theory

Scrum is a framework for developing complex products. It's not a technique or a definitive method.
Scrum addresses complex adaptive problems , while productively and creatively delivering products of the highest possible value.
Scrum is lightweight, simple to understand but difficult to master.
The Scrum framework consists of Scrum Teams (small team of people) and their associated roles , events , artifacts , and rules.
Scrum is used in very diverse areas, from developing software and hardware to managing the operation of organizations and almost everything we use in our daily lives, as individuals and societies.
Scrum is founded on empirical process control theory, or empiricism.
- Empiricism asserts that knowledge comes from experience.
Three pillars uphold every implementation of empirical process control: transparency, inspection, and adaptation (TIA).
- Transparency – Significant aspects of the process must be visible to those responsible for the outcome. Observers need have a common understanding of what is being seen.
- Inspection – Scrum users must regularly inspect Scrum artifacts (product backlog, sprint backlog, the increment) and progress toward a Sprint Goal to detect undesirable results
- Adaptation – As soon as a deviation from the expect result is determined, an adjustment must be made as soon as possible. Scrum prescribes four formal events for inspection and adaptation : Spring Planning, Daily Scrum, Sprint Review, Sprint Retrospective.
The Scrum Values are: commitment, courage, focus, openness and respect (CCFOR). These values are important to bring to life the three pillars of Scrum and build trust to everyone.
- Commitment – Everyone personally commit to achieve the goals of the team.
- Courage – Everyone have courage to do the right thing and work on tough problems.
- Focus – Everyone focuses on the work of the Sprint and the goals of the team.
- Openness – The team and the stakeholders agree to be open about all the work and the challenges to perform it.
- Respect – Everyone respect each other to be capable, independent people.

The Scrum Team

Consists on a Product Owner, the Development Team, and a Scrum Master.
Scrum Teams are:
- Self-organizing – Choose how best to accomplish their work.
- Cross-functional – Everyone has all competencies needed to accomplish the work without depending on others that are not part of the team.
The team model is designed to optimize flexibility , creativity , and productivity.
There is no Project Manager role in Scrum and in general, the Product Owner role is by no means to be confused with a Project Manager. The responsibilities of a Project Manager are distributed between the Product Owner, the Scrum Master and the rest of the team.

Product Owner

The main responsibility is to maximize the value (this value could come in various forms) of the product resulting from work of the Development Team.
Is only one person, not a committee. But can represent the desires of a committee.
Is the sole person responsible for managing the Product Backlog :
- The items on the Product Backlog should be clearly expressed and understood by the Development Team.
- Is responsible for ordering the items in the Product Backlog.
- Ensure that the Product Backlog is visible, transparent, and clear.
- The Product Backlog should show what the Scrum Team will work next.
The Product Owner may do the above work or have the Development Team do it. However, the Product Owner still remains accountable.

Development Team

Their goal is to deliver a potentially releasable Increment of "Done" product at the end of each Sprint.
Only the Development Team can create the Increment.
The Development Team is structured and empowered by the organization to organize and manage their own work.
The teams are self-organizing. Only they made the decisions in how the Product Backlog should be turned into potentially shippable Increments. The benefits are commitment , accountability and creativity. Also optimizes flexibility.
They are cross-functional (the team should have the skills needed to create the Increment). There is no titles in Development Team, even if the work is done for someone. So, the accountability belongs to the Development Team as a whole.
It is possible for the Product Owner or the Scrum Master to be part of the Development Team, but not recommended.
The Development Team should have between 3 to 9 team members.

Scrum Master

The Scrum Master assists the Development Team and the Product Owner and is responsible for promoting and supporting Scrum within the organization. The Scrum Master ensures that everyone understands the Scrum theory, practices, rules and values.
The Scrum Master’s job is to work with the Scrum Team and the organization to increase the transparency of the artifacts. This work usually involves learning, convincing, and change.
The Scrum Master is not a manager, but more like a servant leader.
Scrum Master service to the Product Owner :
- Understanding Scrum and Agile practices.
- Ensuring that goals, scope and product domain are understood.
- Learn effective Product Backlog management.
- Product planning in an empirical environment.
- Can facilitate planning and Backlog refinement.
Scrum Master service to the Development Team :
- Coaches in self-organization and cross-functionality.
- Helps to create high-value products.
- Remove impediments.
- Facilitating Scrum events (not a secretary).
- Coaching the Scrum values.
Scrum Master service to the Organization :
- Coaches the organization.
- Works with other Scrum Masters.
- Cause changes that increase the productivity of the Scrum Team.
- Coaches Scrum and empirical product development.

Scrum Events

Sprint

Timebox of one-month or less. Short enough to keep the business risk acceptable to the Product Owner, and able to synchronize the development work with other business events.
Sprints contain all the prescribed Scrum Events, a flexible plan on how to build a Product Increment and of course the development work needed.
Each Sprint has the Sprint Goal that helps the Development Team better understand why it is building the Increment.
During the Sprint:
- No changes are made that would endanger the Sprint Goal.
- Quality goals do not decrease.
- Scope may be clarified and re-negotiated.
There is no gap between Sprints and nothing happens between Sprints.
A Sprint can be cancelled (very rare).
- Only the Product Owner can do it.
- This can happen if:
- The Sprint Goal becomes obsolete.
- Major changes in the market occur.
- Company decides to change direction.
- If it's canceled:
- Completed items will be reviewed.
- Incomplete items will be re-estimated and put back in the Product Backlog.

Sprint planning

Time-boxed to a maximum of eight hours for a one-month Sprint.
Normally happens after the conclusion of the previous Sprint.
Answers the following:
- What can be delivered in the Increment resulting from the next Sprint.
- How will the work needed would be achieved.
A Spring Goal is defined by the Product Owner and the Development Team. Even if the objective of the Sprint Goal is at first defined by the Product Owner, the number of the Product Backlog items selected is solely up to the Development Team (upon negotiation with the Product Owner). To define this, the following is evaluated:
- Previous Product Increment
- Projected capacity of the Development Team.
- Past performance of the Development Team.
The Development Team can invite people outside the Scrum Team to provide technical or domain advice.
This meeting cannot identify all the work that needs to be done in advance. Only a plan with enough detail so that the development work can start. By the end of the meeting, this plan should be decomposed often to units of one day or less. The Development Team should be able to explain their plan to accomplish the Sprint Goal.
At the end of the meeting, this should be defined:
- The Spring Goal
- The Product Backlog items selected and the plan for delivering them (this is the Spring Backlog)

Daily Scrum

Time-boxed of 15 minutes, every day and at the same time and place.
Only the Development Team attends this meeting. They could allow others to be present, and the Scrum Master has the role to make sure that the team has the meeting.
It's a key to inspect and adapt pillars
The Development Team inspect progress toward completing the work in the Sprint Backlog and reaching the Sprint Goal.
The interactions that the Development Team has should improve communication, identify impediments and promote quick decision making.
Examples of questions to be answered:
- What did I do yesterday?
- What will I do today?
- Do I see any impediment?
If needed, the Development Team can meet immediately after the Daily Scrum to further discuss and decide on how do the rest of the Sprint work will be completed.
This meeting should result in a common understanding of how the Sprint is progressing and what needs to be done next to meet the Sprint Goal.

Spring review

Time-boxed to a maximum of four hours for a one-month Sprint.
Happens at the end of a Sprint to inspect the Increment and adapt the Product Backlog if needed.
The Product Owner owns this meeting and will invite key Stakeholders to this event. The Development Team and the Scrum Master are also present. The Scrum Master role is to facilitate this meeting and to make sure it is held within the time-box.
It's an informal meeting.
The items that have been Done and not Done are explained by the Product Owner.
The Development Team discusses what went well, what were the problems, and how these problems can be resolved.
The Development Team demonstrates the work that is been Done
The Product Owner discusses the Product Backlog and explains when the next release might be available.
The entire group collaborates on what to do next, discusses changes in the marketplace and what is important to do next.
This meeting can result in a revised Product Backlog. The items that were not done, are put back in the Product Backlog.

Spring Retrospective

Time-boxed to a maximum of three hours for a one-month Sprint.
It's the last event before the end of the Sprint. Happens after the Sprint Review and before the Sprint Planning.
The goal of the Sprint Retrospective is for the Scrum Team to inspect itself and the process, and create a plan for improvements for the next sprint.
Only the Scrum Team is present.
The Scrum Master is a facilitator in this meeting, makes sure that everybody understands the purpose and ensures that the meeting is positive and productive and coaches a team to keep the event within the time-box.
The objective is to look into how the last Sprint went with regards to people, relationships, processes, and tools.
Get reflections on what went well and what can be improved.
Create a plan for implementing those improvements in the next Sprint.
The Definition of Done could be improved.
The result of this meeting is the improvements that the Scrum Team will implement in the next Sprint.

Scrum Artifacts

Product Backlog

An ordered list of everything that is known to be needed in the product.
Artifact designed to provide transparency and opportunities for inspection and adaptation.
Single source of all features, functions, requirements, enhancements and fixes for any future changes to be made to the product. As long as the product exists so will its Product Backlog.
Never complete and constantly changing.
The Product Owner is the only responsible for the Product Backlog.
If multiple teams who work on the same Product, only one Product Backlog should be used.
The Product Backlog items characteristics are description, order, estimate and value. Could also have a test description.
The Development Team is responsible for the estimates.
Product Backlog items that are positioned higher in the Product Backlog are more important as they provide much greater value and are usually clearer and more detailed as the items in the lower part of the Product Backlog. The top items are more refined, so they should be small enough to be included in the next Sprint.
The Product Backlog refinement is the act of adding detail, estimates, and order to items. Time-boxed event that should not occupy more than 10 per cent of the capacity of the Development Team.

Sprint Backlog

Set of Product Backlog items selected for the Sprint, plus a plan for delivering the Increment and achieve the Sprint Goal.
The Sprint Backlog should also include at least one important process improvement identified during the last Sprint Retrospective.
Temporary Artifact that exists only during the Sprint.
The Development Team is the only responsible for the Sprint Backlog. If new work is required, the Development Team adds it.
The scope may be clarified and re-negotiated between the Product Owner and Development Team as more is learned.
As work is performed or completed, the estimated remaining work is updated.
The Development Team is responsible for monitoring the progress and the likelihood of reaching the Sprint Goal. This should be tracked at least in every Daily Scrum.

Increment

Is the sum of all Product Backlog Items completed during a Sprint, plus the value of all Increments from all previous Sprints.
At the end of each Sprint, the Increment must be completed according to the Definition of Done.
The Product Owner is the responsible for if and when to release the Increment.

Definition of Done

Every member of the Scrum Team must have a shared understanding of what it means for work to be complete, to ensure transparency.
The purpose of each Sprint is to deliver increments that respect the current definition of Done.
Guides the Development Team in knowing how many Product Backlog items it can select for the Sprint Backlog
Who creates the Definition of Done?
- The Development Organization - Typically most organizations have already development processes in place, standards that must be followed, procedures and quality standards. If there is no convention by the organization, should be the development team to define it.
- The Development Team
- The Development Team of the Scrum Team must define a definition of Done appropriate for the Product if there is none defined by the development organization.
- The Development Team may involve the Product Owner in this process and may define rules and quality criteria that are stricter but still following the Definition of Done that the organization has.
- If there are multiple Scrum Teams, all Development Teams should agree on a definition of Done.

Scrum Terms

Burn-down Chart

A chart which shows the amount of work which is thought to remain a backlog.
Is only related to the remaining work.
Isn't related to project costs or business value, nor related to the productivity of the Development Team.

Burn-up Chart

A chart which shows the amount of work which has been completed.
Provides a visual representation of a Sprint's completed work related to its total scope, which is represented by the number of selected Product Backlog Items

Cone of uncertainty

Describes the evolution of the amount of uncertainty during a project.
As more is learned, uncertainty tends to decrease.

Technical debt

The typically unpredictable overhead of maintaining the product, ofter caused by less than ideal design decisions. Also known as Design Debt or Code Debt.
May exist unintentionally in the Increment or introduced purposefully to realize value earlier.
Technical Debt is something that should be continuously dealt with and not postponed.
Technical Debt is tightly coupled with the quality of the product.

Velocity

Is a measure of the amount of work a Development Team can handle during a typical Sprint.
Is not mandatory in Scrum, and not correlated with value. Only estimates are made, no commitment is done.

Sources:

O que tenho de fazer como trabalhador independente para clientes estrangeiros (IT)

Vitor Oliveira — Sat, 26 Oct 2019 17:21:04 +0000

Atualização 2021: Se o vosso cliente é do Reino Unido, tenham em atenção que já não é preciso fazer a Declaração Recapitulativa devido ao Brexit. As opções que se escolhem em relação ao IVA nos Recibos Verdes e os campos a preencher na Declaração Periódica do IVA, são diferente. Vejam este excelente artigo como referência.

Actualmente, são cada vez mais trabalhadores da área de IT a deixar de ser trabalhadores por contra de outrem para começarem a ser trabalhadores independentes para clientes estrangeiros, vulgo, contractors. No entanto, o mundo dos recibos verdes é complicado e com informação muito dispersa pela Internet. Essa informação por vezes é confusa, desatualizada e ínfima no que se refere a clientes estrangeiros quando comparada com situações de clientes nacionais.

Este artigo tem como objetivo clarificar todas as obrigações fiscais que um trabalhador com actividade aberta tem. Reforço que este artigo é sobre um contribuinte com actividade aberta e não com uma empresa. Para certos valores abrir uma empresa deve compensar, mas nesse caso já é obrigatório terem um contabilista por isso deixem esse trabalho para ele. Uma última nota para referir que o artigo se refere a 2019, podendo daqui a uns meses mudar (vou com certeza atualizar o artigo nessa altura).

Abrir actividade

CAE - Programador e Consultoria (para terem flexibilidade mesmo no futuro)
Informar que o cliente é estrangeiro para ficares isento de IVA (art. 6°)
Ir mesmo a um Serviço de Finanças para ter abertura imediata de actividade, pois se o pedido for submetido pelo portal das Finanças pode demorar 1 semana para aprovação
Para abrir actividade pelo Portal das Finanças, podem ver aqui.
Registar no ViaCTT, pois é obrigatório e dá multa se não o fizerem

Impostos

Segurança Social

Ver código contributivo
Se não isento, basicamente o valor do desconto da SS resume-se ao seguinte: a incidência tributiva é de 70% do valor recebido no trimestre, do qual 21.4% corresponde o valor a pagar de SS nesse trimestre. Obviamente se quisermos calcular o valor anual multiplica-se por 4, se quisermos saber o valor mensal, divide-se por 3.
O Serviço de Finanças comunica automaticamente à Segurança Social que foi aberta atividade
Isenção de 12 meses após abrir actividade no seguinte artigo:

Artigo 145.º
Produção de efeitos
1 - No caso de primeiro enquadramento no regime dos trabalhadores independentes, este só produz efeitos no primeiro dia do 12.º mês posterior ao do início de atividade. (Redação dada pelo Decreto-Lei n.º 2/2018, de 9 de janeiro)

IRS

O rendimento tributável para a categoria B (trabalhador independente) é de 75%. Para atingir estes 25% de “desconto”, é necessário o seguinte:
- 10% automático
- 15% justificado em faturas no âmbito da atividade profissional. Se rendimento inferior a 27.360, não necessita de justificar despesas. Podem ver aqui como se calcula esses 15%
Os 75% de rendimento é tributado de acordo com a tabela simplificada de IRS
- Ter em atenção que se casado e IRS em conjunto, o valor tributável soma com o da outra pessoa e divide por dois

IVA

Isenção de IVA dado que a empresa é estrangeira, dado pelo Artigo 6º
Isenção dada pelo seguinte excerto:

6 - São tributáveis as prestações de serviços efectuadas a: (Redação dada pelo artigo 2.º do Decreto-Lei n.º 186/2009, de 12/08, em vigor a partir de 01/01/2010)
a) Um sujeito passivo dos referidos no n.º 5 do artigo 2.º, cuja sede, estabelecimento estável ou, na sua falta, o domicílio, para o qual os serviços são prestados, se situe no território nacional, onde quer que se situe a sede, estabelecimento estável ou, na sua falta, o domicílio do prestador;

Declarações

Faturas e Recibos Verdes

Periodicidade: mensal
Onde submeter
Dados importantes a inserir:
- Inserir dados da empresa
- Inserir valor a receber/recebido (Importância recebida a título de Pagamento de bens ou serviços)
- Regime do IVA: Regras de localização - art.º 6.º [regras específicas]
- Base de incidência em IRS: Sem retenção - Não residente sem estabelecimento

Declaração recapitulativa do IVA

Esta declaração é obrigatória para empresas de países membros da UE. Devem entregar declaração antes da Declaração periódica do IVA.

Periodicidade
- Até ao dia 20 do mês seguinte, no caso de operações realizadas pelos sujeitos passivos do regime normal de tributação mensal ou com periodicidade trimestral com transmissões intracomunitárias que excedam os 50 mil euros.
- Até ao dia 20 do trimestre seguinte àquele a que respeitam as operações para os sujeitos passivos com periodicidade trimestral, que não excedam 50 mil euros de transmissões intracomunitárias de bens (no trimestre atual ou nos quatro trimestres anteriores).
Onde submeter
Dados importantes a inserir:
- Quadro 04 - Inserir país de destino, NIF/VAT number, Valor e colocar “5 - Prestação de Serviços” no Tipo de Operação

Declaração periódica do IVA

Apesar de estarmos a passar recibos verdes, tal como qualquer trabalhador independente, temos de submeter esta declaração.

Periodicidade
- Até ao dia 15 do segundo mês seguinte ao trimestre a que dizem respeito os serviços (<650 mil euros) - Ou seja, trimestral
- Até ao dia 15 do segundo mês seguinte ao mês a que dizem respeito os serviços (>650 mil euros) - Ou seja, mensal
Onde submeter
Dados importantes a inserir:
- Escolher pré-preenchimento da declaração (neste momento o pré-preenchimento ainda não é excelente)
- Anexo 0 - Selecionar que já foi submetido declaração recapitulativa (4-A)
- Anexo 6 - Aqui, acho que o melhor será olhar para os screenshots. Mas o mais importante é:
  - Quadro 1 - Transmissões intracomunitárias de bens e prestações de serviços mencionadas nas declarações recapitulativas (campo 7) - Inserir o valor total das prestações de serviços tal como no IVA recapitulativo
  - Quadro 5 - Outros bens e serviços (campo 24) - Inserir valor do IVA dos gastos que fizeram no âmbito da actividade
  - Quadro 12 - Aqui têm de escolher se querem reportar excesso e passar para o trimestre seguinte seguinte ou se querem recuperar o IVA
Como recuperar o IVA?
- TBA (se alguém souber qual o correto procedimento para fazer isto, que o diga nos comentários)

Segurança Social (se abrangido)

Periodicidade: Até ao último dia do mês seguinte ao trimestre que terminou. Por exemplo, para o 1º trimestre do ano, o último dia para entrega seria o última dia do mês de Abril
Onde submeter: Segurança Social Direta
Dados importantes a inserir:
- TBA (se alguém tiver uma declaração de exemplo da SS que possa facultar agradecia para poder complementar este artigo)

e-Fatura

Tipicamente até alguns meses antes da submissão anual do IRS. É no entanto aconselhado validar as faturas algumas vezes durante o ano, assinalando aquelas que se relacionam com a actividade profissional (importante para o cálculo da parcela a abater no rendimento tributável do IRS).
Que tipo de gastos são no âmbito da actividade:

Faturas da casa (Internet por completo, restantes apenas parcialmente)
Carro (1 fatura de combustível por mês por exemplo)
Refeições esporádicas
Ter bom senso com comida, bebidas e café
Material de escritório
Mobiliário de escritório
Equipamento electrónico

IRS

Periodicidade: anual
Dados importantes a inserir:
- Anexo B - Rendimentos resultados de trabalho independente, em regime simplificado ou ato isolado
- Anexo SS - Declaração anual de rendimentos a ser enviado à Segurança Social
Pagamento especial por conta: Basicamente, é um adiantamento do IRS que fazemos para o ano seguinte. O valor vem juntamente com o IRS e é pago 3 prestações.

Recursos

Screenshots das declarações
Excel para uma simulação simples do salário liquido anual (façam download para o poderem usar)

Espero que tenham gostado deste artigo e que tem a informação que precisam para este caso em específico.

Conto com a vossa ajuda para poder completar os seguintes pontos em falta:

Como preencher o anexo da SS
Quais são as regras das despesas do IVA? Por exemplo, na questão de uma fatura de combustível, só podemos pedir o reembolso de metade do IVA
Como pedir o reembolso do IVA
Para compras internacionais que fazem logo a dedução do IVA (exemplo: Amazon), é preciso declarar algo? Atenção, que neste ponto só podem registar-se na Amazon com conta empresa se o vosso NIF aparecer no VIES
Tendo em conta que o nosso local de trabalho para as finanças é a nossa casa, pode-se pôr como despesa o passe?
- Sim é possível. Tão válido como meterem uma fatura de um depósito de combustível!
E no caso da renda de casa? Se puser na categoria imóveis do e-Fatura e depois pusermos que a despesa foi no âmbito da nossa actividade o que acontece?
Pode-se pôr nas despesas um recibo de um espaço de co-working?
- Sim é possível.

Qualquer sugestão que tenham para melhorar este artigo, é só dizer!

Disclaimer: Não sou contabilista, apenas um Software Engineer que se aventurou pelo mundo do trabalho independente e que quer partilhar toda a informação que juntou sobre o tema.

The Rules of Logging

Vitor Oliveira — Fri, 27 Sep 2019 17:34:48 +0000

We live in a world where clients want applications developed in an unbelievably short time. We, software engineers, struggle (almost) every time to meet deadlines because we want to deliver the best work that we can. Strict deadlines mean that there’s always a risk that something is left behind: automatic tests, code quality from taking shortcuts, documentation, among other things, can turn a project into a nightmare in the long run.

We are aware of all these critical things, but there is a particular piece of any application that we only remember when we need it: the logs. Yes. The logs are all those letters that you painfully see in your terminal when something goes wrong, and you have your boss asking every 5 minutes why the application is still malfunctioning.

In my career, I learned and absorbed a set of rules to streamline the logging of my applications. Do you find this annoying? Would you prefer to have to stay awake until dawn again, trying to understand why your users are receiving errors when they want to do something trivial? Interested? Then come with me through the W’s that make part of the rules of logging.

What

Before we start on this, you have to remember only one thing: you have to log everything! Every request. I don’t care if it’s a GET, a POST, a PUT, if it had success, if returned some validation error, I don’t care. Log everything.

Do you only log the errors? Sorry, you are doing it wrong! How do you know when a specific user made a request? How are you going to create those wonderful dashboards full of statistics with tools like Kibana or Grafana? Also, of course, another thing that is great for those dashboards is to log the log level itself. It should be mandatory to record if that log entry is an INFO, WARN, ERROR, among others.

Typically, a backend application serves an API (it could be B2B, B2C, but that doesn’t matter). What’s important is that you want to know which service the user just called, so you have to log the name of the endpoint. And even though that name is quite specific, it’s always a good idea to log also the type of HTTP method of the endpoint. What changed? Was a resource created? Was a resource retrieved? How many? Do you see what I mean? This is the data that will become invaluable at some point in your project. Moreover, typically, it’s information that you have at the moment of the response, so you don’t have any excuse not to log it!

Bonus points: thread/request id. It’s always nice to have this when you have to track a lengthy operation that logs many details: like queries or even custom information, which is being recorded at the same time that the application is still receiving other requests. The multiple lines of different logging requests can get mixed up, and it can become a real mess to find anything. The identifier of a request can prevent a situation like this, or it can be quickly resolved with a simple search.

2019–04–06 17:02:30.414 INFO [req-000000086] [c.b.a.controller.ApiController] [operationName=ApiController.getAll, httpMethod=GET, IPAddress=100.200.300.400, userId=55df8919, executionTime=12, size=5] [operationResult=OK]

2019–04–06 12:10:21.741 INFO [req-000000052] [c.b.a.controller.ApiController] [operationName=ApiController.get, httpMethod=GET, IPAddress=100.200.300.400, userId=55df8919, executionTime=5, resourceId=1000] [operationResult=OK]

When

Let’s face it: knowing the time of a situation in the log is the most crucial aspect. So don’t be a fool: if you are using a framework for your language or logging and this isn’t a default value that appears in the log, my friend, you better start googling for alternatives.

The typical format that we are looking for is a human-readable timestamp: YYYY-MM-DD HH:MM:SS.SSS. If you need, you should go down to millisecond precision. Also, of course, pay attention to that thing that haunts you in your sleep: you have to be careful with timezones!

We live in a world where every second count. In 2000, it was acceptable to wait 10 seconds to open a web page but now if it takes more than 1 second the user is going to close that page. So, you are already guessing what I’m going to say: execution time. Every request has to log the corresponding response time. Also, yes, this is a nice one for that fancy chart in your dashboards!

2019–04–06 17:02:03.375 INFO [req-000000083] [c.b.a.controller.ApiController] [operationName=ApiController.edit, httpMethod=PATCH, IPAddress=100.200.300.400, userId=55df8919, executionTime=127] [operationResult=NO_CONTENT]

Who

Every aspect that we’ve talked about until now is essential, but it could become irrelevant if you don’t know who made a specific operation in your application.

Typically you have an authentication system for your application. It doesn’t matter if it’s a REST API with a bearer token or basic auth, or if it’s a web app with a Keycloak, Cierge or AWS Cognito. When the request enters your endpoint, you should have access to the user identifier that made it, and at that moment you should log that identifier. If you have endpoints that allow unauthenticated requests, then you should log something like userId=Anonymous.

If you don’t have an authentication system, you can take another approach and opt to print the IP that made a request. It’s not the most credible identifier (the user could be connected to a network that supports one hundred users but has a static IP, for example), but it’s better than having no clue about who made a specific request. Also, one thing is obvious: if security is your application’s primary concern, independently logging the IP is always essential, whether you have an authentication system or not.

2019–04–07 08:18:04.293 INFO [req-000000016] [c.b.a.controller.ApiController] [operationName=ApiController.create, httpMethod=POST, IPAddress=100.200.300.400, userId=55df8919, executionTime=57, resourceId=1002] [operationResult=CREATED]

Why

Well, this one is obvious from the beginning. Only if the logging of your application is turned off, will you not have the errors printed in your log. So, this is simple: to the client, we always return a pretty message. In the log, we should print every nasty little thing that caused an error. Even that one that will give nightmares because that little bug is your fault!

But not everything revolves around errors. In my opinion, you don’t have to print all the validation errors that you send to the user, but there are some that you should log. For example, there is a trivial one: trying to access a resource that doesn’t exist. The user is going to receive a 404 HTTP code, and the log should reflect that. If you use some tool that identifies those kinds of errors in the log, you could raise alerts based on the number of those events.

2019–04–07 08:24:26.138 WARN [req-000000040] [c.b.a.e.ExceptionHandlingControllerAdvice] [operationName=ApiController.get, httpMethod=GET, IPAddress=100.200.300.400, userId=55df8919, resourceId=123456789, executionTime=4] [operationResult=NOT_FOUND] Resource not found: 123456789

2019–04–07 09:47:13.263 WARN [req-000000055] [c.b.a.e.ExceptionHandlingControllerAdvice] [operationName=ApiController.create, httpMethod=POST, IPAddress=100.200.300.400, userId=55df8919, executionTime=140] [operationResult=CONFLICT] The selected dates are already reserved

Where

In this final section, I want to mention two things that could become handy in certain situations. If your application is an API that serves a frontend application, I’m sure there is valuable browser information that made the request. We all know that dealing with the panoply of browsers that exist nowadays is a nightmare. Help that needy frontend developer with this.

This next one isn’t easily implemented, but I believe that some applications need to log this: the geolocation of the request. You have a lot of APIs to know the location of an IP but calling an API to add information to the log is a little bit expensive.

Conclusion

If you read everything and your log has all the information, you are a superstar. If you have some, I honestly believe that is a good start, and it’s a sign that you care about your project! I highly recommend allocating some time to improve this in your application. As we’ve just seen, it’s so important! If you don’t have anything but the default information, you have much work to do, so hurry up before a user or your client raises a question that you won’t know how to answer!

In my teams, logging is always an essential concern and one of the first things to do when we bootstrap an application. The value of a meaningful and structured logging architecture is immeasurable because it helps us to solve any problem faster and more efficiently. Without logs, your team could be stuck trying to explain why your application is behaving unexpectedly, or it could take hours to respond to a simple client query about an error.

I hope that this article has convinced you about the importance of correct logging within your applications. So believe me, when it comes to logging, there is always room for improvement. It’s a never-ending task. So what are you waiting?

Bonus: You can find here an example for a logback.xml (hello Java and Spring users) that has the same pattern of the examples.