0
# Logging Context System
1

2
Context classes and utilities for organizing logs by CDAP program types, providing structured logging with consistent tagging, filtering capabilities, and program-specific log organization across the CDAP platform.
3

4
## Capabilities
5

6
### LoggingContextHelper
7

8
Utility class for creating and manipulating logging contexts for different program types, providing the primary factory methods for context creation.
9

10
```java { .api }
11
/**
12
 * Creates and manipulates logging contexts for different program types
13
 * Primary factory for creating appropriate logging contexts based on program type
14
 */
15
public final class LoggingContextHelper {
16
    /**
17
     * Create logging context for a CDAP program
18
     * @param namespaceId Namespace identifier
19
     * @param appId Application identifier  
20
     * @param entityId Program/entity identifier
21
     * @param programType Type of CDAP program (SERVICE, WORKFLOW, MAPREDUCE, etc.)
22
     * @return LoggingContext appropriate for the specified program type
23
     */
24
    public static LoggingContext getLoggingContext(String namespaceId, String appId, String entityId, ProgramType programType);
25
    
26
    /**
27
     * Create logging context with run ID for a specific program execution
28
     * @param namespaceId Namespace identifier
29
     * @param appId Application identifier
30
     * @param entityId Program/entity identifier  
31
     * @param programType Type of CDAP program
32
     * @param runId Unique identifier for this program run
33
     * @return LoggingContext with run-specific information
34
     */
35
    public static LoggingContext getLoggingContextWithRunId(String namespaceId, String appId, String entityId, ProgramType programType, String runId);
36
    
37
    /**
38
     * Create filter from logging context
39
     * @param loggingContext Context to create filter from
40
     * @return Filter object for log querying based on context
41
     */
42
    public static Filter createFilter(LoggingContext loggingContext);
43
    
44
    /**
45
     * Extract metrics tags from logging context
46
     * @param loggingContext Context to extract tags from  
47
     * @return Map of tag names to tag values for metrics tagging
48
     */
49
    public static Map<String, String> getMetricsTags(LoggingContext loggingContext);
50
}
51
```
52

53
**Usage Examples:**
54

55
```java
56
import io.cdap.cdap.logging.context.LoggingContextHelper;
57
import io.cdap.cdap.logging.context.LoggingContext;
58
import io.cdap.cdap.common.app.ProgramType;
59

60
// Create context for a service
61
LoggingContext serviceContext = LoggingContextHelper.getLoggingContext(
62
    "myNamespace",           // Namespace
63
    "myApplication",         // Application  
64
    "myService",            // Service name
65
    ProgramType.SERVICE     // Program type
66
);
67

68
// Create context for a specific workflow run
69
LoggingContext workflowRunContext = LoggingContextHelper.getLoggingContextWithRunId(
70
    "myNamespace",
71
    "myApplication", 
72
    "myWorkflow",
73
    ProgramType.WORKFLOW,
74
    "run-12345"             // Specific run ID
75
);
76

77
// Create filter for log queries
78
Filter logFilter = LoggingContextHelper.createFilter(serviceContext);
79

80
// Extract metrics tags for correlation
81
Map<String, String> metricsTags = LoggingContextHelper.getMetricsTags(serviceContext);
82
```
83

84
### Base Application Context
85

86
Base context class for applications, providing common functionality for all program types.
87

88
```java { .api }
89
/**
90
 * Base context for applications
91
 * Provides common logging context functionality for all CDAP programs
92
 */
93
public class ApplicationLoggingContext extends AbstractLoggingContext {
94
    /**
95
     * Create application logging context
96
     * @param namespaceId Namespace identifier
97
     * @param applicationId Application identifier
98
     * @param runId Run identifier (optional)
99
     */
100
    public ApplicationLoggingContext(String namespaceId, String applicationId, String runId);
101
    
102
    /**
103
     * Get the log partition for this context
104
     * Used for organizing logs in storage systems
105
     * @return String representing the log partition
106
     */
107
    public String getLogPartition();
108
}
109
```
110

111
### Service Context
112

113
Logging context for user-defined services with handler-specific tagging.
114

115
```java { .api }
116
/**
117
 * Context for user-defined services
118
 * Provides logging context for CDAP user services with handler support
119
 */
120
public class UserServiceLoggingContext extends ApplicationLoggingContext {
121
    /** Tag name for user service ID */
122
    public static final String TAG_USER_SERVICE_ID = ".userserviceid";
123
    
124
    /** Tag name for handler ID within the service */
125
    public static final String TAG_HANDLER_ID = ".userhandlerid";
126
    
127
    /**
128
     * Create user service logging context
129
     * @param namespaceId Namespace identifier
130
     * @param applicationId Application identifier
131
     * @param serviceId User service identifier
132
     * @param runId Run identifier (optional)
133
     */
134
    public UserServiceLoggingContext(String namespaceId, String applicationId, String serviceId, String runId);
135
    
136
    /**
137
     * Get the log partition for this service context
138
     * @return String representing the log partition for this service
139
     */
140
    public String getLogPartition();
141
}
142
```
143

144
### Workflow Context
145

146
Logging context for workflow programs with workflow-specific tagging.
147

148
```java { .api }
149
/**
150
 * Context for workflow programs  
151
 * Provides logging context for CDAP workflow executions
152
 */
153
public class WorkflowLoggingContext extends ApplicationLoggingContext {
154
    /** Tag name for workflow ID */
155
    public static final String TAG_WORKFLOW_ID = ".workflowid";
156
    
157
    /**
158
     * Create workflow logging context
159
     * @param namespaceId Namespace identifier
160
     * @param applicationId Application identifier
161
     * @param workflowId Workflow identifier
162
     * @param runId Run identifier (optional)
163
     */
164
    public WorkflowLoggingContext(String namespaceId, String applicationId, String workflowId, String runId);
165
    
166
    /**
167
     * Get the log partition for this workflow context
168
     * @return String representing the log partition for this workflow
169
     */
170
    public String getLogPartition();
171
}
172
```
173

174
### Workflow Program Context
175

176
Specialized context for programs running within workflows.
177

178
```java { .api }
179
/**
180
 * Context for programs within workflows
181
 * Provides logging context for programs executed as part of a workflow
182
 */
183
public class WorkflowProgramLoggingContext extends WorkflowLoggingContext {
184
    /**
185
     * Create workflow program logging context
186
     * @param namespaceId Namespace identifier
187
     * @param applicationId Application identifier  
188
     * @param workflowId Workflow identifier
189
     * @param programType Type of program within workflow
190
     * @param programId Program identifier within workflow
191
     * @param runId Run identifier (optional)
192
     */
193
    public WorkflowProgramLoggingContext(String namespaceId, String applicationId, String workflowId, ProgramType programType, String programId, String runId);
194
    
195
    /**
196
     * Get the log partition for this workflow program context
197
     * @return String representing the log partition for this workflow program
198
     */
199
    public String getLogPartition();
200
}
201
```
202

203
### MapReduce Context
204

205
Logging context for MapReduce programs with job-specific tagging.
206

207
```java { .api }
208
/**
209
 * Context for MapReduce programs
210
 * Provides logging context for CDAP MapReduce job executions
211
 */
212
public class MapReduceLoggingContext extends ApplicationLoggingContext {
213
    /** Tag name for MapReduce job ID */
214
    public static final String TAG_MAP_REDUCE_JOB_ID = ".mapreducejobid";
215
    
216
    /**
217
     * Create MapReduce logging context
218
     * @param namespaceId Namespace identifier
219
     * @param applicationId Application identifier
220
     * @param mapReduceId MapReduce program identifier
221
     * @param runId Run identifier (optional)
222
     */
223
    public MapReduceLoggingContext(String namespaceId, String applicationId, String mapReduceId, String runId);
224
    
225
    /**
226
     * Get the log partition for this MapReduce context
227
     * @return String representing the log partition for this MapReduce job
228
     */
229
    public String getLogPartition();
230
}
231
```
232

233
### Spark Context
234

235
Logging context for Spark programs with job-specific tagging.
236

237
```java { .api }
238
/**
239
 * Context for Spark programs
240
 * Provides logging context for CDAP Spark job executions  
241
 */
242
public class SparkLoggingContext extends ApplicationLoggingContext {
243
    /** Tag name for Spark job ID */
244
    public static final String TAG_SPARK_JOB_ID = ".sparkjobid";
245
    
246
    /**
247
     * Create Spark logging context
248
     * @param namespaceId Namespace identifier
249
     * @param applicationId Application identifier
250
     * @param sparkId Spark program identifier
251
     * @param runId Run identifier (optional)
252
     */
253
    public SparkLoggingContext(String namespaceId, String applicationId, String sparkId, String runId);
254
    
255
    /**
256
     * Get the log partition for this Spark context
257
     * @return String representing the log partition for this Spark job
258
     */
259
    public String getLogPartition();
260
}
261
```
262

263
### Worker Context
264

265
Logging context for worker programs with worker-specific tagging.
266

267
```java { .api }
268
/**
269
 * Context for worker programs
270
 * Provides logging context for CDAP worker program executions
271
 */
272
public class WorkerLoggingContext extends ApplicationLoggingContext {
273
    /** Tag name for worker ID */
274
    public static final String TAG_WORKER_ID = ".workerid";
275
    
276
    /**
277
     * Create worker logging context
278
     * @param namespaceId Namespace identifier
279
     * @param applicationId Application identifier
280
     * @param workerId Worker program identifier
281
     * @param runId Run identifier (optional)
282
     */
283
    public WorkerLoggingContext(String namespaceId, String applicationId, String workerId, String runId);
284
    
285
    /**
286
     * Get the log partition for this worker context
287
     * @return String representing the log partition for this worker
288
     */
289
    public String getLogPartition();
290
}
291
```
292

293
**Context Usage Examples:**
294

295
```java
296
import io.cdap.cdap.logging.context.*;
297
import io.cdap.cdap.common.app.ProgramType;
298

299
// Service context with handler
300
UserServiceLoggingContext serviceContext = new UserServiceLoggingContext(
301
    "production",           // Namespace
302
    "data-pipeline",       // Application
303
    "http-service",        // Service ID  
304
    "run-67890"           // Run ID
305
);
306

307
// MapReduce context
308
MapReduceLoggingContext mrContext = new MapReduceLoggingContext(
309
    "analytics", 
310
    "batch-processor",
311
    "daily-aggregation",
312
    "run-11111"
313
);
314

315
// Workflow with embedded program
316
WorkflowLoggingContext workflowContext = new WorkflowLoggingContext(
317
    "etl",
318
    "data-ingestion", 
319
    "nightly-workflow",
320
    "run-22222"
321
);
322

323
WorkflowProgramLoggingContext workflowProgramContext = new WorkflowProgramLoggingContext(
324
    "etl",
325
    "data-ingestion",
326
    "nightly-workflow", 
327
    ProgramType.MAPREDUCE,
328
    "transform-step",
329
    "run-22222"
330
);
331

332
// Extract partition information for storage
333
String servicePartition = serviceContext.getLogPartition();
334
String mrPartition = mrContext.getLogPartition();
335
```
336

337
## Context Tag Constants
338

339
Each logging context class defines public constants for tag names used in log organization and filtering:
340

341
```java { .api }
342
// User Service Context Tags
343
public static final String TAG_USER_SERVICE_ID = ".userserviceid";
344
public static final String TAG_HANDLER_ID = ".userhandlerid";
345

346
// Workflow Context Tags  
347
public static final String TAG_WORKFLOW_ID = ".workflowid";
348

349
// MapReduce Context Tags
350
public static final String TAG_MAP_REDUCE_JOB_ID = ".mapreducejobid";
351

352
// Spark Context Tags
353
public static final String TAG_SPARK_JOB_ID = ".sparkjobid";
354

355
// Worker Context Tags
356
public static final String TAG_WORKER_ID = ".workerid";
357
```
358

359
These tag constants are used internally for consistent log tagging and can be used by external code for log filtering and querying operations.