Skip to content

Commit c4c7602

Browse files
bhufmannbhufmann
committed
doc: Add a developer guide tailored for trace-server development
- Add developer guide in markdown in doc/trace-server folder - Update and create example classes in the o.e.tc.example.core plug-in Signed-off-by: Bernd Hufmann <[email protected]>
1 parent 4aeaf73 commit c4c7602

17 files changed

+4427
-9
lines changed

‎doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4782,11 +4782,11 @@ Data providers are queried with a filter object, which usually contains a time r
47824782
* RUNNING if the response was returned before the underlying analysis was completed, and querying the provider again with the same parameters can return a different model.
47834783
* COMPLETED if the underlying analysis is finished and we do not expect a different response for the query parameters.
47844784
4785-
''Note that a complete example of analysis and data provider can be found in the [https://github.com/eclipse-tracecompass/org.eclipse.tracecompass/blob/master/doc/org.eclipse.tracecompass.examples.core org.eclipse.tracecompass.examples.core plugin sources] and [https://github.com/eclipse-tracecompass/org.eclipse.tracecompass/blob/master/doc/org.eclipse.tracecompass.examples.ui org.eclipse.tracecompass.examples.ui plugin sources] respectively.''
4785+
''Note that a complete example of analysis, data provider and views can be found in the [https://github.com/eclipse-tracecompass/org.eclipse.tracecompass/blob/master/doc/org.eclipse.tracecompass.examples org.eclipse.tracecompass.examples plugin sources].''
47864786
47874787
== Data provider types ==
47884788
4789-
The base data provider '''ITmfDataProvider''' is the interface each data provider type has to implement. The data provider factories create instances of such provider type. Tree data providers are of type '''ITmfTreeDataProvider''' extend the '''ITmfDataProvider''' interface and returns a tree, as a list of '''TmfTreeDataModel''', with a name, ID and parent ID. The ID is unique to a provider type and the parent ID indicates which element from the list is the entry's parent to rebuild the tree hierarchy from the list of models. Note such tree need to have limited size to not exceed the available memory.
4789+
The base data provider '''ITmfDataProvider''' interface is the interface each data provider type has to implement. The data provider factories create instances of such provider type. Tree data providers are of type '''ITmfTreeDataProvider''' extend the '''ITmfDataProvider''' interface and returns a tree, as a list of '''TmfTreeDataModel''', with a name, ID and parent ID. The ID is unique to a provider type and the parent ID indicates which element from the list is the entry's parent to rebuild the tree hierarchy from the list of models. Note such tree need to have limited size to not exceed the available memory.
47904790
47914791
The base '''TimeGraphEntryModel''' class extends this with a start time and end time. Concrete classes are free to add other fields, which can be used in the Eclipse Trace Context where the UI code can access the model type. However, in Trace Compass server context only fields defined in the Trace Server protocol will be serialized.
47924792

‎doc/org.eclipse.tracecompass.examples.core/META-INF/MANIFEST.MF‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,12 @@ Bundle-ActivationPolicy: lazy
1414
Bundle-RequiredExecutionEnvironment: JavaSE-17
1515
Export-Package: org.eclipse.tracecompass.examples.core,
1616
org.eclipse.tracecompass.examples.core.analysis,
17-
org.eclipse.tracecompass.examples.core.data.provider
17+
org.eclipse.tracecompass.examples.core.analysis.config,
18+
org.eclipse.tracecompass.examples.core.data.provider,
19+
org.eclipse.tracecompass.examples.core.data.provider.config
1820
Bundle-Vendor: %Bundle-Vendor
19-
Import-Package: com.google.common.collect
21+
Import-Package: com.google.common.collect,
22+
com.google.gson;version="2.8.2",
23+
com.google.gson.annotations;version="2.8.2",
24+
com.google.gson.reflect;version="2.8.2"
2025
Automatic-Module-Name: org.eclipse.tracecompass.examples.core

‎doc/org.eclipse.tracecompass.examples.core/plugin.xml‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,15 @@
1212
class="org.eclipse.tracecompass.tmf.core.trace.TmfTrace">
1313
</tracetype>
1414
</module>
15+
<module
16+
id="org.eclipse.tracecompass.examples.state.system.module.config"
17+
name="Example State System Module"
18+
analysis_module="org.eclipse.tracecompass.examples.core.analysis.config.ExampleConfigurableStateSystemAnalysisModule"
19+
automatic="false">
20+
<tracetype
21+
class="org.eclipse.tracecompass.tmf.core.trace.TmfTrace">
22+
</tracetype>
23+
</module>
1524
</extension>
1625
<extension point="org.eclipse.tracecompass.tmf.core.dataprovider">
1726
<dataProviderFactory
@@ -23,8 +32,16 @@
2332
id="org.eclipse.tracecompass.examples.xy.dataprovider">
2433
</dataProviderFactory>
2534
<dataProviderFactory
26-
class="org.eclipse.tracecompass.examples.core.data.provider.ExampleEventsStatisticsDataProviderFactory"
35+
class="org.eclipse.tracecompass.examples.core.data.provider.ExampleDataTreeDataProviderFactory"
2736
id="org.eclipse.tracecompass.examples.nomodulestats">
2837
</dataProviderFactory>
38+
<dataProviderFactory
39+
class="org.eclipse.tracecompass.examples.core.data.provider.config.ExampleConfigurableDataTreeDataProviderFactory"
40+
id="org.eclipse.tracecompass.examples.nomodulestats.config">
41+
</dataProviderFactory>
42+
<dataProviderFactory
43+
class="org.eclipse.tracecompass.examples.core.data.provider.config.ExampleConfigurableTimeGraphProviderFactory"
44+
id="org.eclipse.tracecompass.examples.timegraph.dataprovider.config">
45+
</dataProviderFactory>
2946
</extension>
3047
</plugin>

‎doc/org.eclipse.tracecompass.examples.core/schema/example-schema-cpu.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://org.eclipse.tracecompass/example-schema.json",
4+
"title": "Example Schema",
5+
"description": "Example Schema for event statistics",
6+
"type": "object",
7+
"properties": {
8+
"filter": {
9+
"description": "filter regular expressions",
10+
"type": "string"
11+
}
12+
},
13+
"required": ["filter"]
14+
}

‎doc/org.eclipse.tracecompass.examples.core/schema/example-schema.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://org.eclipse.tracecompass/example-schema.json",
4+
"title": "Example Schema for cpu",
5+
"description": "Example Schema for cpu",
6+
"type": "object",
7+
"properties": {
8+
"filter": {
9+
"description": "cpu number",
10+
"type": "number"
11+
}
12+
},
13+
"required": ["filter"]
14+
}

‎doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/Activator.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@
1919
*/
2020
public class Activator extends Plugin {
2121

22+
/** The plug-in ID */
23+
public static String PLUGIN_ID = "org.eclipse.tracecompass.examples.core"; //$NON-NLS-1$
24+
2225
// ------------------------------------------------------------------------
2326
// Attributes
2427
// ------------------------------------------------------------------------

‎doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/analysis/config/ExampleConfigurableStateProvider.java‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
/*******************************************************************************
2+
* Copyright (c) 2020, 2025 École Polytechnique de Montréal and others
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License 2.0 which
6+
* accompanies this distribution, and is available at
7+
* https://www.eclipse.org/legal/epl-2.0/
8+
*
9+
* SPDX-License-Identifier: EPL-2.0
10+
*******************************************************************************/
11+
12+
package org.eclipse.tracecompass.examples.core.analysis.config;
13+
14+
import java.util.Map;
15+
import java.util.Objects;
16+
17+
import org.eclipse.jdt.annotation.NonNull;
18+
import org.eclipse.jdt.annotation.Nullable;
19+
import org.eclipse.tracecompass.statesystem.core.ITmfStateSystemBuilder;
20+
import org.eclipse.tracecompass.tmf.core.config.ITmfConfiguration;
21+
import org.eclipse.tracecompass.tmf.core.event.ITmfEvent;
22+
import org.eclipse.tracecompass.tmf.core.event.aspect.TmfCpuAspect;
23+
import org.eclipse.tracecompass.tmf.core.statesystem.AbstractTmfStateProvider;
24+
import org.eclipse.tracecompass.tmf.core.statesystem.ITmfStateProvider;
25+
import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
26+
import org.eclipse.tracecompass.tmf.core.trace.TmfTraceUtils;
27+
28+
import com.google.gson.Gson;
29+
import com.google.gson.JsonSyntaxException;
30+
import com.google.gson.annotations.Expose;
31+
import com.google.gson.annotations.SerializedName;
32+
33+
/**
34+
* An example of a simple state provider for a simple state system analysis
35+
*
36+
* This module is also in the developer documentation of Trace Compass. If it is
37+
* modified here, the doc should also be updated.
38+
*
39+
* @author Alexandre Montplaisir
40+
* @author Geneviève Bastien
41+
* @author Bernd Hufmann
42+
*/
43+
public class ExampleConfigurableStateProvider extends AbstractTmfStateProvider {
44+
45+
private static final @NonNull String PROVIDER_ID = "org.eclipse.tracecompass.examples.state.system.module.config"; //$NON-NLS-1$
46+
private static final int VERSION = 0;
47+
private int fCpu = -1;
48+
49+
/**
50+
* Constructor
51+
*
52+
* @param trace
53+
* the trace
54+
* @param configuration
55+
* the configuration
56+
*/
57+
public ExampleConfigurableStateProvider(@NonNull ITmfTrace trace, @Nullable ITmfConfiguration configuration) {
58+
super(trace, PROVIDER_ID + (configuration == null ? "" : ":" + configuration.getId())); //$NON-NLS-1$ //$NON-NLS-2$
59+
if (configuration != null) {
60+
try {
61+
String jsonParameters = new Gson().toJson(configuration.getParameters(), Map.class);
62+
@SuppressWarnings("null")
63+
Integer cpu = new Gson().fromJson(jsonParameters, InternalConfiguration.class).getCpu();
64+
if (cpu != null) {
65+
fCpu = cpu.intValue();
66+
}
67+
} catch (JsonSyntaxException e) {
68+
fCpu = -1;
69+
}
70+
}
71+
}
72+
73+
/**
74+
* Constructor
75+
*
76+
* @param trace
77+
* The trace for this state provider
78+
*/
79+
public ExampleConfigurableStateProvider(@NonNull ITmfTrace trace) {
80+
super(trace, PROVIDER_ID);
81+
}
82+
83+
@Override
84+
public int getVersion() {
85+
return VERSION;
86+
}
87+
88+
@Override
89+
public @NonNull ITmfStateProvider getNewInstance() {
90+
return new ExampleConfigurableStateProvider(getTrace());
91+
}
92+
93+
@Override
94+
protected void eventHandle(ITmfEvent event) {
95+
96+
/**
97+
* Do what needs to be done with this event, here is an example that
98+
* updates the CPU state and TID after a sched_switch
99+
*/
100+
if (event.getName().equals("sched_switch")) { //$NON-NLS-1$
101+
102+
final long ts = event.getTimestamp().getValue();
103+
Long nextTid = event.getContent().getFieldValue(Long.class, "next_tid"); //$NON-NLS-1$
104+
Integer cpu = TmfTraceUtils.resolveIntEventAspectOfClassForEvent(event.getTrace(), TmfCpuAspect.class, event);
105+
if (cpu == null || nextTid == null || (fCpu >= 0 && cpu != fCpu)) {
106+
return;
107+
}
108+
109+
ITmfStateSystemBuilder ss = Objects.requireNonNull(getStateSystemBuilder());
110+
int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(cpu)); //$NON-NLS-1$
111+
// The main quark contains the tid of the running thread
112+
ss.modifyAttribute(ts, nextTid, quark);
113+
114+
// The status attribute has an integer value
115+
int statusQuark = ss.getQuarkRelativeAndAdd(quark, "Status"); //$NON-NLS-1$
116+
Integer value = (nextTid > 0 ? 1 : 0);
117+
ss.modifyAttribute(ts, value, statusQuark);
118+
}
119+
}
120+
121+
122+
private static class InternalConfiguration {
123+
@Expose
124+
@SerializedName(value = "cpu")
125+
private @Nullable Integer fCpuValue = null;
126+
127+
public @Nullable Integer getCpu() {
128+
return fCpuValue;
129+
}
130+
}
131+
}

‎doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/analysis/config/ExampleConfigurableStateSystemAnalysisModule.java‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
/*******************************************************************************
2+
* Copyright (c) 2020, 2025 École Polytechnique de Montréal and others
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License 2.0 which
6+
* accompanies this distribution, and is available at
7+
* https://www.eclipse.org/legal/epl-2.0/
8+
*
9+
* SPDX-License-Identifier: EPL-2.0
10+
*******************************************************************************/
11+
12+
package org.eclipse.tracecompass.examples.core.analysis.config;
13+
14+
import java.util.Objects;
15+
16+
import org.eclipse.jdt.annotation.NonNull;
17+
import org.eclipse.jdt.annotation.Nullable;
18+
import org.eclipse.tracecompass.tmf.core.config.ITmfConfiguration;
19+
import org.eclipse.tracecompass.tmf.core.statesystem.ITmfStateProvider;
20+
import org.eclipse.tracecompass.tmf.core.statesystem.TmfStateSystemAnalysisModule;
21+
22+
/**
23+
* An example of a simple state system analysis module.
24+
*
25+
* This module is also in the developer documentation of Trace Compass. If it is
26+
* modified here, the doc should also be updated.
27+
*
28+
* @author Geneviève Bastien
29+
* @author Bernd Hufmann
30+
*/
31+
public class ExampleConfigurableStateSystemAnalysisModule extends TmfStateSystemAnalysisModule {
32+
33+
/**
34+
* Module ID
35+
*/
36+
public static final String ID = "org.eclipse.tracecompass.examples.state.system.module.config"; //$NON-NLS-1$
37+
38+
/**
39+
* The configuration to apply.
40+
*/
41+
private ITmfConfiguration fConfiguration = null;
42+
43+
/**
44+
* Default constructor
45+
*/
46+
public ExampleConfigurableStateSystemAnalysisModule() {
47+
super();
48+
}
49+
50+
/**
51+
* Constructor
52+
*
53+
* @param configuration
54+
* the configuration
55+
*/
56+
public ExampleConfigurableStateSystemAnalysisModule(ITmfConfiguration configuration) {
57+
fConfiguration = configuration;
58+
if (configuration != null) {
59+
setId(ID + ":" + fConfiguration.getId()); //$NON-NLS-1$
60+
}
61+
}
62+
63+
@Override
64+
protected @NonNull ITmfStateProvider createStateProvider() {
65+
return new ExampleConfigurableStateProvider(Objects.requireNonNull(getTrace()), fConfiguration);
66+
}
67+
68+
@Override
69+
public @Nullable ITmfConfiguration getConfiguration() {
70+
return fConfiguration;
71+
}
72+
}

doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/data/provider/ExampleEventsStatisticsDataProvider.java renamed to doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/data/provider/ExampleDataTreeDataProvider.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
*/
4343
@SuppressWarnings("null")
4444
@NonNullByDefault
45-
public class ExampleEventsStatisticsDataProvider implements ITmfTreeDataProvider<TmfTreeDataModel> {
45+
public class ExampleDataTreeDataProvider implements ITmfTreeDataProvider<TmfTreeDataModel> {
4646
private static long fCount = 0;
4747

4848
private @Nullable ITmfTrace fTrace;
@@ -54,7 +54,7 @@ public class ExampleEventsStatisticsDataProvider implements ITmfTreeDataProvider
5454
* @param trace
5555
* the trace (not experiment)
5656
*/
57-
public ExampleEventsStatisticsDataProvider(ITmfTrace trace) {
57+
public ExampleDataTreeDataProvider(ITmfTrace trace) {
5858
fTrace = trace;
5959
}
6060

doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/data/provider/ExampleEventsStatisticsDataProviderFactory.java renamed to doc/org.eclipse.tracecompass.examples.core/src/org/eclipse/tracecompass/examples/core/data/provider/ExampleDataTreeDataProviderFactory.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
/**
3030
* Example data provider factory
3131
*/
32-
public class ExampleEventsStatisticsDataProviderFactory implements IDataProviderFactory {
32+
public class ExampleDataTreeDataProviderFactory implements IDataProviderFactory {
3333
private static final String ID = "org.eclipse.tracecompass.examples.nomodulestats"; //$NON-NLS-1$
3434

3535
private static final IDataProviderDescriptor DESCRIPTOR = new DataProviderDescriptor.Builder()
@@ -44,7 +44,7 @@ public class ExampleEventsStatisticsDataProviderFactory implements IDataProvider
4444
if (trace instanceof TmfExperiment) {
4545
return TmfTreeCompositeDataProvider.create(TmfTraceManager.getTraceSet(trace), ID);
4646
}
47-
return new ExampleEventsStatisticsDataProvider(trace);
47+
return new ExampleDataTreeDataProvider(trace);
4848
}
4949

5050
@SuppressWarnings("null")

0 commit comments

Comments
 (0)