# introspect a specific stage
werf build --introspect-stage [IMAGE_NAME/]STAGE_NAME

# introspect a stage before or after execution of a dysfunctional set of instructions
werf build --introspect-error
werf build --introspect-before-error

Writing a configuration is especially difficult at the beginning because you do not quite understand what is in the stage assembly container when the instructions are executed.

In the process of assembling, you can access a certain stage using introspection options. During introspection, like during assembling, the stage assembly container contains service tools and environment variables. Tools are presented as a set of utilities required during assembling. They are added by mounting the directories from service containers of our stapel distributions (available at /.werf/stapel path in the assembly container). Introspection comes down the fact that the stage assembly container is launched for users in interactive mode.

The --introspect-stage option can be used multiple times to introspect several stages. There are the following formats to use:

  • specify IMAGE_NAME/STAGE_NAME to introspect stage STAGE_NAME of either image or artifact IMAGE_NAME. The nameless image can be defined by ~.;
  • specify STAGE_NAME or */STAGE_NAME for the introspection of all existing stages with name STAGE_NAME.

During development, introspection makes it possible to achieve the required outcomes in an assembly container, and then transfer all the steps and instructions into the configuration of the appropriate stage. This approach is useful when the set objective is clear, although the steps to achieve it are not so obvious and require a great deal of experiment.

During debugging, introspection allows you to see why assembling ended with an error or the result was unexpected, to check whether dependent files are present and to check the system state.

Finally, when introspection is effected for applications that use ansible, you can debug ansible playbooks in the assembly container and subsequently transfer ansible tasks to the appropriate configuration stages.