0
# File Writer
1

2
Low-level writer for protocol buffers to event files, providing fine-grained control over TensorBoard event file creation and management. Used internally by SummaryWriter but available for direct use when manual event handling is needed.
3

4
## Capabilities
5

6
### Initialization
7

8
Creates a FileWriter for direct protocol buffer event file management with configurable queue and flush settings.
9

10
```python { .api }
11
class FileWriter:
12
    def __init__(
13
        self,
14
        logdir: str,
15
        max_queue: int = 10,
16
        flush_secs: int = 120,
17
        filename_suffix: str = ''
18
    ):
19
        """
20
        Creates a FileWriter for protocol buffer event files.
21

22
        Parameters:
23
        - logdir: Directory where event files will be written
24
        - max_queue: Maximum number of pending events and summaries before flush (default: 10)
25
        - flush_secs: Seconds between automatic flushes to disk (default: 120)
26
        - filename_suffix: Suffix added to all event filenames in logdir
27
        """
28
```
29

30
### Directory Management
31

32
Access and manage the log directory for the writer.
33

34
```python { .api }
35
def get_logdir(self) -> str:
36
    """
37
    Returns the directory where event files will be written.
38

39
    Returns:
40
    str: The log directory path
41
    """
42
```
43

44
### Event Management
45

46
Add raw events and summaries directly to the event file with precise control over timing and metadata.
47

48
```python { .api }
49
def add_event(
50
    self,
51
    event,
52
    step: Optional[int] = None,
53
    walltime: Optional[float] = None
54
):
55
    """
56
    Add a raw event to the event file.
57

58
    Parameters:
59
    - event: Protocol buffer Event object
60
    - step: Global step value (uses event.step if None)
61
    - walltime: Timestamp (uses current time if None)
62
    """
63

64
def add_summary(
65
    self,
66
    summary,
67
    global_step: Optional[int] = None,
68
    walltime: Optional[float] = None
69
):
70
    """
71
    Add a summary protocol buffer to the event file.
72

73
    Parameters:
74
    - summary: Protocol buffer Summary object
75
    - global_step: Global step value for the summary
76
    - walltime: Timestamp (uses current time if None)
77
    """
78
```
79

80
### Graph Management
81

82
Add computational graphs directly as protocol buffers to the event file.
83

84
```python { .api }
85
def add_graph(
86
    self,
87
    graph_profile,
88
    walltime: Optional[float] = None
89
):
90
    """
91
    Add graph and step stats to the event file.
92

93
    Parameters:
94
    - graph_profile: Graph protocol buffer or RunMetadata
95
    - walltime: Timestamp (uses current time if None)
96
    """
97

98
def add_onnx_graph(
99
    self,
100
    graph,
101
    walltime: Optional[float] = None
102
):
103
    """
104
    Add ONNX graph to TensorBoard.
105

106
    Parameters:
107
    - graph: ONNX graph protocol buffer
108
    - walltime: Timestamp (uses current time if None)
109
    """
110

111
def add_openvino_graph(
112
    self,
113
    graph,
114
    walltime: Optional[float] = None
115
):
116
    """
117
    Add OpenVINO graph to TensorBoard.
118

119
    Parameters:
120
    - graph: OpenVINO graph protocol buffer
121
    - walltime: Timestamp (uses current time if None)
122
    """
123
```
124

125
### File Control
126

127
Manage file flushing, closing, and reopening for precise control over event file lifecycle.
128

129
```python { .api }
130
def flush(self):
131
    """
132
    Flush pending events and summaries to disk.
133
    Call this method to ensure all pending events are written.
134
    """
135

136
def close(self):
137
    """
138
    Flush all data to disk and close the event file.
139
    Call when no longer need the writer.
140
    """
141

142
def reopen(self):
143
    """
144
    Reopen the EventFileWriter after closing.
145
    Can be called after close() to add more events in the same directory.
146
    Events will go into a new event file.
147
    Does nothing if the writer was not closed.
148
    """
149
```
150

151
### Metadata Management
152

153
Set default metadata for multiple operations using context managers.
154

155
```python { .api }
156
def use_metadata(self, *, global_step=None, walltime=None):
157
    """
158
    Context manager to temporarily set default metadata for enclosed add_event calls.
159

160
    Parameters:
161
    - global_step: Default global step value for enclosed operations
162
    - walltime: Default walltime for enclosed operations (uses time.time() if None)
163

164
    Returns:
165
    Context manager that sets default metadata
166
    """
167
```
168

169
## Usage Examples
170

171
### Direct Event Creation
172

173
```python
174
from tensorboardX import FileWriter
175
from tensorboardX.proto import event_pb2, summary_pb2
176
import time
177

178
# Create writer
179
writer = FileWriter('logs/direct_events')
180

181
# Create custom event
182
event = event_pb2.Event()
183
event.wall_time = time.time()
184
event.step = 100
185

186
# Create custom summary
187
summary = summary_pb2.Summary()
188
value = summary.value.add()
189
value.tag = 'custom_metric'
190
value.simple_value = 42.0
191

192
# Add to event file
193
writer.add_summary(summary, global_step=100)
194
writer.flush()
195
writer.close()
196
```
197

198
### Using Context Manager
199

200
```python
201
from tensorboardX import FileWriter
202

203
# Context manager usage
204
with FileWriter('logs/context') as writer:
205
    # Set default metadata for multiple operations
206
    with writer.use_metadata(global_step=50):
207
        # Add multiple events with the same step
208
        writer.add_event(custom_event1)
209
        writer.add_event(custom_event2)
210
        writer.add_event(custom_event3)
211
```
212

213
### Manual File Lifecycle Management
214

215
```python
216
from tensorboardX import FileWriter
217

218
writer = FileWriter('logs/manual_control', max_queue=5, flush_secs=60)
219

220
# Add events manually
221
for i in range(100):
222
    writer.add_summary(create_summary(i), global_step=i)
223
    
224
    # Force flush every 10 steps
225
    if i % 10 == 0:
226
        writer.flush()
227

228
# Close and reopen for new data
229
writer.close()
230
writer.reopen()
231

232
# Add more events to new file
233
for i in range(100, 200):
234
    writer.add_summary(create_summary(i), global_step=i)
235

236
writer.close()
237
```
238

239
## Error Handling
240

241
FileWriter operations can raise exceptions for invalid paths, permission errors, and protocol buffer issues:
242

243
```python
244
from tensorboardX import FileWriter
245
import os
246

247
try:
248
    # May fail if directory doesn't exist or no write permissions
249
    writer = FileWriter('/invalid/path')
250
except OSError as e:
251
    print(f"Failed to create writer: {e}")
252

253
try:
254
    # Ensure directory exists
255
    os.makedirs('logs/safe_path', exist_ok=True)
256
    writer = FileWriter('logs/safe_path')
257
    
258
    # Use writer safely
259
    writer.add_summary(summary, global_step=0)
260
    
261
finally:
262
    writer.close()
263
```
264

265
## Cloud Storage Support
266

267
FileWriter supports writing directly to cloud storage with appropriate URLs:
268

269
```python
270
# S3 storage (requires boto3)
271
writer = FileWriter('s3://mybucket/tensorboard-logs/experiment1')
272

273
# Google Cloud Storage (requires google-cloud-storage)  
274
writer = FileWriter('gs://mybucket/tensorboard-logs/experiment1')
275
```