Bugzilla – Full Text Bug Listing
| Summary: | (Doc)Need to adjust docs for the Linux IA32 platform to use the new AC version | ||
|---|---|---|---|
| Product: | z_Archived | Reporter: | Karla Callaghan <karla.callaghan> |
| Component: | TPTP | Assignee: | jkubasta |
| Status: | CLOSED FIXED | QA Contact: | |
| Severity: | normal | ||
| Priority: | P1 | CC: | guru.nagarajan, haggarty, igor.alelekov, jkubasta, kiryl.kazakevich, nmehrega, paulslau, samwai |
| Version: | unspecified | Keywords: | plan |
| Target Milestone: | --- | ||
| Hardware: | PC | ||
| OS: | Linux | ||
| Whiteboard: | closed460 | ||
| Bug Depends on: | 125103 | ||
| Bug Blocks: | |||
| Attachments: | |||
|
Description
Karla Callaghan
Setting target and priority. Retarget to 4.4. Postponing the introduction of the new AC running in backwards compatibility mode on the Linux platform. Correct source content to remove translatability issues. Corrected the 8?? level problems cited. Unable to find any "115 (W) Questionable TM markup table:" issue. The cited HTML-32 reference does not exist. I believe the current version satisfies translatability requirements. Reopened because incorrectly thought I was working on (and closing) Bug 171585. Please reassign this defect to me. Reassigned per request. This effort is needed when new AC with backwards compatibility is working on Linux and replaces the RAC download pkg. There are several areas that will need attention: 1)Getting Started doc - Included in the runtime package of the agent controller. To get the needed content, there will need to be some melding together of the Linux getting started docs for RAC and AC, using the Windows version which was done for 4.3 as the model (found in src-native-new/packaging_md/windows). 2)Index pages which list Agent Controller by platform will need to have the link for the Linux platform pointed at AC doc vs. RAC. 3)Examine the agentcontroller.doc.isv and agentcontroller.doc.user plugins for TOC xml pages that need modification. 4) Check the TPTP and Platform web pages for links that need pointing to AC vs RAC content. sizing added I have updated the Linux Getting Started document and would appreciate your reviewing it. I question whether bolded items are needed. Other questions I have include: Will the install be a simple unzip? What changes are needed for TI Agent? Are there any IAC items that need to be added? Are there any 64-bit specifics that need to be added? Is there/should there be a "Working With the Agent Controller" document for Linux the way there is for Windows? Created attachment 63228 [details]
updated getting started manual
Created attachment 63229 [details]
This is the Getting Started manual
Hi Joanna, Here are the answers to your questions: > I question whether bolded items are needed. Yes, they're definitely needed. > Are there any IAC items that need to be added? Since, the getting started doc is specific to the stand-alone Agent Controller, I don't think we should indicate anything specific to IAC. However, we can quickly mention that IAC is suppose to eliminate the need for installing/configuring the Agent Controller. They can be referred to an IAC-specific doc if they're further interested. Here are the modifications that I think you should make to the document: LINE: <install-dir> = The absolute directory path where the Agent Controller has been unzipped. For example: C:/opt/tptpAC CORRECTION: There is no "C:" in linux. Might want to change this to /opt/tptpAC LINE: Download one of the Linux Agent Controller Runtime packages from the TPTP Downloads area. CORRECTION: Download one of the Linux Agent Controller Runtime packages from the TPTP Download page. <"Download page" sounds better than "Downloads area"> LINE: Note: Do not encase the environment variable's value in double quotes even if there are spaces in the <install-dir> path. JK: Please confirm this is Windows specific CORRECTION: Yes, this is Windows specific. Spaces are not allowed in folder names for Linux. LINE: Start the Agent Controller by changing your working directory to <install-dir>/bin and running either RAStart.sh or ACStart.sh. CORRECTION: I don't think we should give the two scripts for starting the Agent Controller. Otherwise, we'll have to explain the difference between the two. Since the only difference is backward compatibility and mosts users don't care about backward compatibility, we should only provide RAStart.sh in the docs. LINE: Stop the Agent Controller by changing your working directory to <install-dir>/bin and running either RAStop.sh or ACStop.sh. CORRECTION: Same comments as above for RAStart.sh/ACStart.sh LINE: The Java Profiler consists of a Profiling Agent packaged as a library (DLL). CORRECTION: It's not a DLL file on Linux. Might want to remove the "(DLL)" part. LINE: -XrunpiAgent[:agent_parm[,agent_parm]* CORRECTION: Missing a square bracket at the end. Thanks Navid. I have made the changes with the exception of linking to IAC documentation (I need to find what we have). I will post the revised file in case anyone else has any other changes (incl TI agent references) before I commit the revisions. Created attachment 63264 [details]
Includes Navid's suggested changes.
I don't agree that "RAStart/Stop" should be the script names specified in this doc. The "RA" prefix is meaningless. In the Windows version of the doc, we expressed the choice between ACStart and RAStart as follows:
Start the Agent Controller by changing your working directory to <install- dir>\bin and running ACServer.exe.
Note: The Agent Controller may also be started up under the name "RAServer".
We put the new script name as the first option because the "AC" prefix makes more sense to a new user wanting to start the "Agent Controller". There is no need to explain why there is a second name if you put it in an aside Note like suggested above. People familiar with the old name will understand why there are 2 names and there is no need to explain to new users. For the ACStop script, we didn't bother putting in the alternative name, but a similar note could be added.
I agree, it would be fine if it's specified as an aside note, but not the way it was previously. Regarding Joanna's questions in comment #9: Will the install be a simple unzip? You need to run the configuration script too, but the install guide covers this by pointing the user to the Getting Started guide. What changes are needed for TI Agent? I'll leave this to someone who knows the differences between using the PI and TI Agent. The original info in the Getting Started on the Java Profiler was all based on the PI agent. Are there any IAC items that need to be added? I ran across a doc link that briefly talked about IAC vs agent controller, but now I can't find it. The only IAC info needed inside the AC Getting Started would be something about, not doing the things in Getting Started if IAC is in use since it does the AC start for you. Are there any 64-bit specifics that need to be added? There should be no 64-bit specifics in the user-level docs that explain how to use AC. I don't know if anything is exposed that needs explaining for the profiler. (There have been problems in mixing 64-bit jvm use with a 32-bit AC package, but that should be handled in release notes.) Is there/should there be a "Working With the Agent Controller" document for Linux the way there is for Windows? You need to cleanup all the platform-specific references to the "Working With the Agent Controller" documents. There are currently such links for Windows, Linux, HP-UX, AIX, and various other AC platforms. The Window's version already points to all new AC info. The Linux version currently points to RAC info, so it needs to be changed to point to the same info that the Window's version does. Note that the information discussed in the "Working with" docs is NOT platform specific. This contains overview info and how to configure the AC to do various things, which involves the changing of XML. The platform-specific division was only needed to split AC vs. RAC documentation info. If all the non-AC platforms are being dropped so that only AC configuration info is needed - the cleanest solution would be to go back to having a single non-platform link to the "Working with" docs (pointing to the new AC info) and drop the platform name from the title. Thanks Karla for your feedback. I have added back the AC* commands with a note re RA* and backward compatibility. I have added an Overview section at the top of the file to explain IAC vs AC. There are changes I need to make to other files (incl IAC) and I will get to those shortly. Created attachment 63355 [details]
Addressing Karla's comments
Your additions look good. I just looked at the document. The following changes are needed for in the docs a) The Java Profiler support has changed. We support JVMTI for 1.5 and JVMPI for 1.4. Joanna, Please replace the Java Profiler section with the attachment that I have added. b) The platforms supported for 4.4 are Win & Linux (32,X86_64 & IPF). Other platforms are not supported for 4.4 and hence should not show up in the main page. Created attachment 63391 [details]
Java Profiler command line support for TPTP 4.4.
(In reply to comment #19) > Created an attachment (id=63355) [details] > Addressing Karla's comments > Minor formatting issue; extend the courier font in bullet 4 of 'Configuring Agent Controller' to include <install-dir>/lib. 1. I have updated the entire "Profiling a Java Application" section based on Guru's input. Note that I did not use the provided input verbatim. Please review the entire section as I made editorial changes, updates based on menu names, clarifications as to what needs to be installed where, formatting changes, removed Windows references (I will open another defect to update the Windows GS), and removed the related information section. Please also note that I did *not* update the agent_parm values for JVMPI. The original getting started doc differs from what Guru has. The major difference is the inclusion of a profile=profile file under JVMPI in Guru's file which is not included in the Getting Started. 2. I have also made Paul's requested revision. 3. I have yet to update the index, TOC, links, main page. Created attachment 64509 [details]
Updates based on Guru's and Paul's comments
*** Bug 183517 has been marked as a duplicate of this bug. *** (In reply to comment #25) > Created an attachment (id=64509) [details] > Updates based on Guru's and Paul's comments > Looks good. Thanks Joanna for refining this document. Web changes will be made under defect https://bugs.eclipse.org/bugs/show_bug.cgi?id=143511. All other changes made. Fixed As of TPTP 4.6.0, TPTP is in maintenance mode and focusing on improving quality by resolving relevant enhancements/defects and increasing test coverage through test creation, automation, Build Verification Tests (BVTs), and expanded run-time execution. As part of the TPTP Bugzilla housecleaning process (see http://wiki.eclipse.org/Bugzilla_Housecleaning_Processes), this enhancement/defect is verified/closed by the Project Lead since this enhancement/defect has been resolved and unverified for more than 1 year and considered to be fixed. If this enhancement/defect is still unresolved and reproducible in the latest TPTP release (http://www.eclipse.org/tptp/home/downloads/), please re-open. As of TPTP 4.6.0, TPTP is in maintenance mode and focusing on improving quality by resolving relevant enhancements/defects and increasing test coverage through test creation, automation, Build Verification Tests (BVTs), and expanded run-time execution. As part of the TPTP Bugzilla housecleaning process (see http://wiki.eclipse.org/Bugzilla_Housecleaning_Processes), this enhancement/defect is verified/closed by the Project Lead since this enhancement/defect has been resolved and unverified for more than 1 year and considered to be fixed. If this enhancement/defect is still unresolved and reproducible in the latest TPTP release (http://www.eclipse.org/tptp/home/downloads/), please re-open. |