Man: move [SESSION] before options
[lttng-tools.git] / doc / man / lttng-health-check.3
CommitLineData
2df048c2
DG
1.TH LTTNG_HEALTH_CHECK 3 2012-09-19 "LTTng" "LTTng Developer Manual"
2.SH NAME
05ec9ff7
DG
3.B DEPRECATED
4
2df048c2
DG
5lttng_health_check \- Monitor health of the session daemon
6.SH SYNOPSIS
7.nf
8.B #include <lttng/lttng.h>
9.sp
10.BI "int lttng_health_check(enum lttng_health_component c);
11.fi
12
13Link with -llttng-ctl.
14.SH DESCRIPTION
15The
16.BR lttng_health_check ()
17is used to check the session daemon health for either a specific component
18.BR c
19or for all of them. Each component represent a subsystem of the session daemon.
20Those components are set with health counters that are atomically incremented
21once reached. An even value indicates progress in the execution of the
22component. An odd value means that the code has entered a blocking state which
23is not a poll(7) wait period.
24
25A bad health is defined by a fatal error code path reached or any IPC used in
26the session daemon that was blocked for more than 20 seconds (default timeout).
27The condition for this bad health to be detected is that one or many of the
28counters are odd.
29
30The health check mechanism of the session daemon can only be reached through
31the health socket which is a different one from the command and the application
32socket. An isolated thread serves this socket and only computes the health
33counters across the code when asked by the lttng control library (using this
34call). This subsystem is highly unlikely to fail due to its simplicity.
35
36The
37.BR c
38argument can be one of the following values:
39.TP
40.BR LTTNG_HEALTH_CMD
41Command subsystem which handles user commands coming from the liblttng-ctl or
42the
43.BR lttng(1)
44command line interface.
45.TP
46.BR LTTNG_HEALTH_APP_MANAGE
47The session daemon manages application socket in order to route client command
48and check if they get closed which indicates the application shutdown.
49.TP
50.BR LTTNG_HEALTH_APP_REG
51The application registration mechanism is an important and vital part of for
52user space tracing. Upon startup, applications instrumented with
53.BR lttng-ust(3)
54try to register to the session daemon through this subsystem.
55.TP
56.BR LTTNG_HEALTH_KERNEL
57Monitor the Kernel tracer streams and main channel of communication
58(/proc/lttng). If this component malfunction, the Kernel tracer is not usable
59anymore by lttng-tools.
60.TP
61.BR LTTNG_HEALTH_CONSUMER
62The session daemon can spawn up to
63.BR three
64consumer daemon for kernel, user space 32 and 64 bit. This subsystem monitors
65the consumer daemon(s). A bad health state means that the consumer(s) are not
66usable anymore hence likely making tracing not usable.
67.TP
68.BR LTTNG_HEALTH_ALL
69Check all components. If only one of them is in a bad state, a health check
70error is returned.
71
72.SH "RETURN VALUE"
73Return 0 if the health is OK, or 1 is it's in a bad state. A return code of \-1
74indicates that the control library was not able to connect to the session
75daemon health socket.
76
77.SH "LIMITATIONS"
78
79For the LTTNG_HEALTH_CONSUMER, you can not know which consumer daemon has
80failed but only that either the consumer subsystem has failed or that a
81lttng-consumerd died.
82
83.SH "AUTHORS"
9b22d135
JG
84lttng-health-check was originally written by David Goulet and is currently
85maintained by Jérémie Galarneau <jeremie.galarneau@efficios.com>.
This page took 0.032632 seconds and 4 git commands to generate.